@llm4ts/runner 2.19.0 → 2.20.0

package/src/AgentTreeSurface.ts

@@ -0,0 +1,202 @@
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Queue from "effect/Queue"
+import * as Ref from "effect/Ref"
+import type * as Scope from "effect/Scope"
+import * as Semaphore from "effect/Semaphore"
+import * as Stream from "effect/Stream"
+import { awaitConsumed, type FlowEventHub } from "@llm4ts/flow/FlowEvents"
+import {
+  emptyTree,
+  initialView,
+  onTreeKey,
+  reduceTree,
+  renderTree,
+  type TreeView
+} from "./AgentTree.ts"
+import type { TerminalSurface } from "./Terminal.ts"
+
+/**
+ * The agent tree inside a running flow (`llm4ts run <flow> --ui tree`,
+ * ADR 0022): a full-screen view fed from the run's event hub, in front of the
+ * classic surface. While it shows, the classic event lines and status block
+ * are silent; `q` hands the screen back to them for the rest of the run, and
+ * the run's end leaves the last frame on screen before the summary.
+ */
+
+export interface AgentTreeOutput {
+  readonly write: (text: string) => Effect.Effect<void>
+  readonly columns: () => number | undefined
+  readonly rows: () => number | undefined
+  readonly colour: boolean
+}
+
+export interface AgentTreeHost {
+  /** The surface the runner and the classic consumer write to. */
+  readonly surface: TerminalSurface
+  /** Catches up with the run's events, leaves the full screen and prints the last frame. */
+  readonly close: Effect.Effect<void>
+}
+
+const enterScreen = "\u001b[?1049h\u001b[?25l"
+const leaveScreen = "\u001b[?25h\u001b[?1049l"
+const home = "\u001b[H\u001b[2J"
+const redrawEvery = "100 millis"
+
+export const makeAgentTreeHost = Effect.fn("@llm4ts/runner/AgentTreeSurface.make")(function* (
+  hub: FlowEventHub,
+  classic: TerminalSurface,
+  output: AgentTreeOutput,
+  keys: Stream.Stream<string>
+): Effect.fn.Return<AgentTreeHost, never, Scope.Scope> {
+  const state = yield* Ref.make(emptyTree())
+  const view = yield* Ref.make<TreeView>(initialView)
+  const active = yield* Ref.make(true)
+  const consumed = yield* Ref.make(0)
+  const lock = yield* Semaphore.make(1)
+
+  const subscription = yield* hub.subscribe
+  yield* Stream.fromSubscription(subscription).pipe(
+    Stream.runForEach((event) =>
+      Effect.flatMap(Clock.currentTimeMillis, (at) =>
+        Ref.update(state, (current) => reduceTree(current, { _tag: "Event", at, event }))
+      ).pipe(Effect.andThen(Ref.update(consumed, (count) => count + 1)))
+    ),
+    Effect.forkScoped
+  )
+
+  const render = (rows: number | undefined): Effect.Effect<string> =>
+    Effect.gen(function* () {
+      const lines = renderTree(yield* Ref.get(state), {
+        width: Math.max(90, output.columns() ?? 90),
+        colour: output.colour,
+        view: yield* Ref.get(view),
+        ...(rows === undefined ? {} : { height: rows })
+      })
+      return lines.join("\n")
+    })
+  /** The full screen fits the terminal; the last frame left behind is whole. */
+  const frame = render(undefined)
+  const screen = Effect.suspend(() => render(output.rows()))
+
+  /** Runs `effect` only while the tree has the screen, under the drawing lock. */
+  const whileShown = (effect: Effect.Effect<void>): Effect.Effect<void> =>
+    lock.withPermit(Effect.flatMap(Ref.get(active), (shown) => (shown ? effect : Effect.void)))
+
+  const leave = (withFrame: boolean): Effect.Effect<void> =>
+    whileShown(
+      Effect.gen(function* () {
+        yield* Ref.set(active, false)
+        yield* output.write(withFrame ? `${leaveScreen}${yield* frame}\n` : leaveScreen)
+      })
+    )
+
+  yield* output.write(enterScreen)
+  yield* Effect.addFinalizer(() => leave(false))
+  yield* Effect.forever(
+    Effect.andThen(
+      Effect.sleep(redrawEvery),
+      whileShown(Effect.flatMap(screen, (text) => output.write(`${home}${text}`)))
+    )
+  ).pipe(Effect.forkScoped)
+  yield* Stream.runForEach(keys, (key) =>
+    Effect.gen(function* () {
+      const next = onTreeKey(yield* Ref.get(view), key, yield* Ref.get(state))
+      if (next === "quit") {
+        return yield* leave(false)
+      }
+      yield* Ref.set(view, next)
+    })
+  ).pipe(Effect.forkScoped)
+
+  const surface: TerminalSurface = {
+    palette: classic.palette,
+    log: (line) =>
+      Effect.flatMap(Ref.get(active), (shown) => (shown ? Effect.void : classic.log(line))),
+    setStatus: (label) =>
+      Effect.flatMap(Ref.get(active), (shown) => (shown ? Effect.void : classic.setStatus(label))),
+    // A prompt needs the ordinary screen: step out of the tree for its length.
+    suspend: (effect) =>
+      Effect.flatMap(Ref.get(active), (shown) =>
+        shown
+          ? Effect.acquireUseRelease(
+              lock.withPermit(Effect.andThen(Ref.set(active, false), output.write(leaveScreen))),
+              () => classic.suspend(effect),
+              () =>
+                lock.withPermit(Effect.andThen(Ref.set(active, true), output.write(enterScreen)))
+            )
+          : classic.suspend(effect)
+      )
+  }
+
+  return {
+    surface,
+    close: Effect.andThen(awaitConsumed(hub, consumed), leave(true))
+  }
+})
+
+// ── node wiring ─────────────────────────────────────────────────────────────
+
+const keyNames: Readonly<Record<string, string>> = {
+  "\u001b[A": "up",
+  "\u001b[B": "down",
+  "\u001b[C": "right",
+  "\u001b[D": "left",
+  "\r": "enter",
+  "\n": "enter",
+  "\u001b": "escape"
+}
+
+const ctrlC = "\u0003"
+
+/** Raw terminal input as key names; a burst of plain characters is one key each. */
+export const keyNamesOf = (chunk: string): ReadonlyArray<string> => {
+  const named = keyNames[chunk]
+  if (named !== undefined) {
+    return [named]
+  }
+  return chunk.startsWith("\u001b") ? [] : [...chunk]
+}
+
+/**
+ * The terminal's keys while the tree has it (raw mode). Raw mode swallows
+ * the interrupt signal, so ctrl-c is handled here: `detach` quits the viewer
+ * (`watch`), `interrupt` raises SIGINT so a run aborts as it always has.
+ */
+export const nodeTreeKeys = (ctrlCMeans: "detach" | "interrupt"): Stream.Stream<string> =>
+  Stream.callback<string>((queue) =>
+    Effect.acquireRelease(
+      Effect.sync(() => {
+        const input = process.stdin
+        if (!input.isTTY) {
+          return undefined
+        }
+        const onData = (data: Buffer) => {
+          const chunk = data.toString("utf8")
+          if (chunk === ctrlC) {
+            if (ctrlCMeans === "interrupt") {
+              process.kill(process.pid, "SIGINT")
+            } else {
+              Queue.offerUnsafe(queue, "q")
+            }
+            return
+          }
+          for (const key of keyNamesOf(chunk)) {
+            Queue.offerUnsafe(queue, key)
+          }
+        }
+        input.setRawMode(true)
+        input.resume()
+        input.on("data", onData)
+        return onData
+      }),
+      (onData) =>
+        Effect.sync(() => {
+          if (onData !== undefined) {
+            process.stdin.off("data", onData)
+            process.stdin.setRawMode(false)
+            process.stdin.pause()
+          }
+        })
+    )
+  )

package/src/FlowArgs.ts

@@ -32,6 +32,7 @@ commands:
 environment:
   LLM4TS_CODER            coding agent: claude|codex|gemini|pi|agy|grok|cursor|opencode (default: claude)
   LLM4TS_VERBOSITY        terminal verbosity: quiet|normal|verbose
+  LLM4TS_UI               tree: the full-screen agent tree (ADR 0022; q returns to the classic view)
   OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY
                           credentials for API providers
 

package/src/FlowRunner.ts

@@ -1,6 +1,8 @@
 import { join } from "node:path"
+import * as Cause from "effect/Cause"
 import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
 import * as Ref from "effect/Ref"
 import type * as Scope from "effect/Scope"
 import type { ConnectorConfig } from "@llm4ts/core/ConnectorConfig"
@@ -55,7 +57,8 @@ import {
   type FlowEventsShape
 } from "@llm4ts/flow/FlowEvents"
 import { FlowContext, type ContextOptions, type FlowContextShape } from "@llm4ts/flow/FlowContext"
-import { makeFlowRecorder } from "@llm4ts/flow/FlowRecorder"
+import { makeFlowRecorder, type RunOutcome } from "@llm4ts/flow/FlowRecorder"
+import { makeAgentTreeHost, nodeTreeKeys } from "./AgentTreeSurface.ts"
 import { makeJudgmentLog, type JudgmentLogShape } from "@llm4ts/flow/JudgmentLog"
 import { makeGitHubTool } from "@llm4ts/flow/GitHubTool"
 import { makeGitTool } from "@llm4ts/flow/GitTool"
@@ -748,7 +751,24 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
     options.costLedgerPath ??
     (persistRun ? join(options.workDir, ".llm4ts", CostLedgerFileName) : undefined)
   const tracker = bundle.tracker
-  const surface = options.surface ?? (yield* makeTerminalSurface(environment))
+  const classic = options.surface ?? (yield* makeTerminalSurface(environment))
+  // The agent tree (ADR 0022) takes the screen only where it fits: a real
+  // terminal, colour allowed, at least 90 columns; the classic view otherwise.
+  const tree =
+    options.surface === undefined && wantsAgentTree(environment, process.stdout, process.stdin)
+      ? yield* makeAgentTreeHost(
+          bundle.events,
+          classic,
+          {
+            write: (text) => Effect.sync(() => void process.stdout.write(text)),
+            columns: () => process.stdout.columns,
+            rows: () => process.stdout.rows,
+            colour: true
+          },
+          nodeTreeKeys("interrupt")
+        )
+      : undefined
+  const surface = tree?.surface ?? classic
   const palette = surface.palette
   const terminal = yield* consumeTerminalEvents(bundle.events, surface, verbosity, {
     timestamps: environment.LLM4TS_TIMESTAMPS === "1" || environment.LLM4TS_TIMESTAMPS === "true"
@@ -827,8 +847,12 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
             surface.log(palette.fail(`cost ledger not written: ${describeFlowError(error)}`))
           )
         )
-  return yield* body(bundle.context).pipe(
-    Effect.provideService(FlowContext, bundle.context),
+  const context: FlowContextShape =
+    tracePath === undefined
+      ? bundle.context
+      : { ...bundle.context, trace: { runId: bundle.runId, path: tracePath } }
+  return yield* body(context).pipe(
+    Effect.provideService(FlowContext, context),
     Effect.andThen((value) => Effect.as(enforceBudget, value)),
     Effect.ensuring(
       Effect.all(
@@ -859,6 +883,7 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
                 )
               )
         ),
+        Effect.andThen(tree === undefined ? Effect.void : tree.close),
         Effect.andThen(appendLedger),
         Effect.andThen(surface.setStatus(undefined)),
         Effect.andThen(tracker.summary),
@@ -896,10 +921,32 @@ export const runWithBundle = Effect.fn("@llm4ts/runner/FlowRunner.runWithBundle"
           )}`
         )
       })
+    ),
+    // Last, after every event is in: the trace's final line says how it ended.
+    Effect.onExit((exit) =>
+      recorder === undefined ? Effect.void : recorder.end(runOutcomeOf(exit))
     )
   )
 })
 
+const wantsAgentTree = (
+  environment: Readonly<Record<string, string | undefined>>,
+  output: { readonly isTTY?: boolean; readonly columns?: number },
+  input: { readonly isTTY?: boolean }
+): boolean =>
+  environment.LLM4TS_UI === "tree" &&
+  environment.NO_COLOR === undefined &&
+  output.isTTY === true &&
+  input.isTTY === true &&
+  (output.columns ?? 0) >= 90
+
+const runOutcomeOf = <A, E>(exit: Exit.Exit<A, E>): RunOutcome =>
+  Exit.isSuccess(exit)
+    ? "completed"
+    : Cause.hasInterruptsOnly(exit.cause)
+      ? "interrupted"
+      : "failed"
+
 export const runEmbedded = Effect.fn("@llm4ts/runner/FlowRunner.runEmbedded")(function* <A, E, R>(
   options: FlowRunnerOptions,
   body: (context: FlowContextShape) => Effect.Effect<A, E, R>,

package/src/Terminal.ts

@@ -11,6 +11,7 @@ import {
   awaitConsumed,
   type FlowEvent,
   type FlowEventHub,
+  rosterEventMessage,
   type ReviewFindings
 } from "@llm4ts/flow/FlowEvents"
 
@@ -33,11 +34,14 @@ export const parseVerbosity = (value: string | undefined): Verbosity => {
 export const rendersEvent = (verbosity: Verbosity, event: FlowEvent): boolean => {
   switch (event._tag) {
     // Advise mode publishes a separate Info event for the operator; progress
-    // feeds the status rows; a blackboard run is for the trace file. None is
-    // a line of its own.
+    // feeds the status rows; a blackboard run is for the trace file; a lease
+    // ending is routine; the story's outcome already says whether the judge
+    // cleared it. None is a line of its own.
     case "JudgmentObserved":
     case "BlackboardRun":
     case "UsageProgress":
+    case "ExecutorReleased":
+    case "StoryJudged":
       return false
     case "StageStarted":
     case "StageCompleted":
@@ -237,6 +241,7 @@ export const terminalLine = (
     case "JudgmentObserved":
     case "BlackboardRun":
     case "UsageProgress":
+    case "StoryJudged":
       return ""
     case "StageStarted":
       return palette.stageStart(safe(event.stage))
@@ -266,6 +271,14 @@ export const terminalLine = (
       return palette.fail(`capability unenforceable: ${safe(event.detail)}`)
     case "Declassified":
       return palette.info(`declassified: ${safe(event.label)}`)
+    case "ExecutorLeased":
+    case "ExecutorReleased":
+    case "ExecutorExcluded":
+    case "ExecutorResumed":
+    case "ExecutorHandedOver": {
+      const message = rosterEventMessage(event)
+      return message === undefined ? "" : palette.info(safe(message))
+    }
   }
 }
 

package/src/Watch.ts

@@ -0,0 +1,291 @@
+import { readdirSync, existsSync, statSync } from "node:fs"
+import { join } from "node:path"
+import * as Duration from "effect/Duration"
+import * as Effect from "effect/Effect"
+import * as Queue from "effect/Queue"
+import * as Ref from "effect/Ref"
+import * as Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import { Board, BoardVersion } from "@llm4ts/flow/BoardSync"
+import { readEpicRuns, type EpicRun } from "@llm4ts/flow/EpicRuns"
+import type { FlowError } from "@llm4ts/flow/FlowError"
+import { loadVersioned, type PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { readTrace } from "@llm4ts/flow/Replay"
+import {
+  emptyTree,
+  initialView,
+  onTreeKey,
+  reduceTree,
+  renderTree,
+  treeInputsOfTrace,
+  type TreeInput,
+  type TreeState,
+  type TreeView
+} from "./AgentTree.ts"
+import { nodeTreeKeys } from "./AgentTreeSurface.ts"
+import { nodeListTraces, TraceDirectoryName } from "./Costs.ts"
+import { nodePlainFileStore } from "./NodePlainFileStore.ts"
+
+/**
+ * `llm4ts watch` (ADR 0022): the agent tree over a trace file — a live run
+ * followed as it grows, a finished run's last frame, or a replay on the
+ * trace's own timestamps. The trace is the only source; the epic's board
+ * adds the stories that have not started.
+ */
+
+export interface WatchOptions {
+  readonly repo: string
+  /** A trace file; the newest in the repository's `.llm4ts/` when omitted. */
+  readonly trace?: string
+  /** An epic id: its latest recorded run. */
+  readonly epic?: string
+  readonly replay?: boolean
+  /** Replay speed-up (default 10). */
+  readonly speed?: number
+}
+
+export interface WatchOutput {
+  readonly write: (text: string) => Effect.Effect<void>
+  readonly columns: () => number | undefined
+  readonly rows: () => number | undefined
+  /** A terminal a person looks at: full-screen, keys, following. */
+  readonly interactive: boolean
+  readonly colour: boolean
+}
+
+export interface WatchDependencies {
+  readonly files: PlainFileStoreShape
+  readonly listTraces: (directory: string) => ReadonlyArray<string>
+  /** Epic folder names under `.llm4ts/epics/`. */
+  readonly listEpics: (directory: string) => ReadonlyArray<string>
+  readonly output: WatchOutput
+  /** Key names as `onTreeKey` reads them: "up", "enter", "q", … */
+  readonly keys: Stream.Stream<string>
+}
+
+export class WatchTargetMissing extends Schema.TaggedError<WatchTargetMissing>()(
+  "WatchTargetMissing",
+  { message: Schema.String }
+) {}
+
+interface WatchTarget {
+  readonly tracePath: string
+  readonly epicDir: string | undefined
+  readonly run: EpicRun | undefined
+}
+
+const epicsDirOf = (repo: string): string => join(repo, TraceDirectoryName, "epics")
+
+/** The epic whose `runs.jsonl` names this trace, if one does. */
+const epicOfTrace = (
+  tracePath: string,
+  repo: string,
+  dependencies: WatchDependencies
+): Effect.Effect<{ readonly dir: string; readonly run: EpicRun } | undefined, FlowError> =>
+  Effect.gen(function* () {
+    const epicsDir = epicsDirOf(repo)
+    for (const epic of dependencies.listEpics(epicsDir)) {
+      const dir = join(epicsDir, epic)
+      const run = [...(yield* readEpicRuns(dependencies.files, dir))]
+        .reverse()
+        .find((candidate) => candidate.tracePath === tracePath)
+      if (run !== undefined) {
+        return { dir, run }
+      }
+    }
+    return undefined
+  })
+
+const resolveTarget = (
+  options: WatchOptions,
+  dependencies: WatchDependencies
+): Effect.Effect<WatchTarget, FlowError | WatchTargetMissing> =>
+  Effect.gen(function* () {
+    if (options.epic !== undefined) {
+      const dir = join(epicsDirOf(options.repo), options.epic)
+      const run = (yield* readEpicRuns(dependencies.files, dir)).at(-1)
+      if (run === undefined) {
+        return yield* WatchTargetMissing.make({
+          message: `epic ${options.epic} has no recorded run in ${dir}/runs.jsonl`
+        })
+      }
+      return { tracePath: run.tracePath, epicDir: dir, run }
+    }
+    const tracePath =
+      options.trace ?? dependencies.listTraces(join(options.repo, TraceDirectoryName)).at(-1)
+    if (tracePath === undefined) {
+      return yield* WatchTargetMissing.make({
+        message: `no trace in ${join(options.repo, TraceDirectoryName)}; pass a trace file or --epic`
+      })
+    }
+    const epic = yield* epicOfTrace(tracePath, options.repo, dependencies)
+    return { tracePath, epicDir: epic?.dir, run: epic?.run }
+  })
+
+const actionWords = (run: EpicRun | undefined): string | undefined => {
+  if (run === undefined) {
+    return undefined
+  }
+  switch (run.action) {
+    case "RunPlan":
+      return "run plan"
+    case "RunRound":
+      return `round ${run.round ?? "?"}`
+    case "PlanRound":
+      return `plan round ${run.round ?? "?"}`
+    case "Land":
+      return "land"
+    default:
+      return run.action
+  }
+}
+
+/** The tree before any event: the epic's board, when the trace belongs to one. */
+const startingTree = (
+  target: WatchTarget,
+  files: PlainFileStoreShape
+): Effect.Effect<TreeState, FlowError> =>
+  Effect.gen(function* () {
+    const action = actionWords(target.run)
+    if (target.epicDir === undefined) {
+      return emptyTree(action === undefined ? {} : { action })
+    }
+    const boardDir =
+      target.run?.round === undefined
+        ? target.epicDir
+        : join(target.epicDir, "rounds", String(target.run.round))
+    const board = yield* loadVersioned(files, join(boardDir, "board.json"), BoardVersion, Board)
+    const epicId = target.epicDir.split("/").at(-1) ?? "epic"
+    return emptyTree({
+      title: board === undefined ? `epic ${epicId}` : board.title.replace(/^Epic:\s*/u, "epic "),
+      stories: (board?.items ?? []).map((item) => ({ id: item.id, status: item.status })),
+      ...(action === undefined ? {} : { action })
+    })
+  })
+
+const readInputs = (
+  target: WatchTarget,
+  files: PlainFileStoreShape
+): Effect.Effect<ReadonlyArray<TreeInput>, FlowError> =>
+  Effect.map(readTrace(files, target.tracePath), treeInputsOfTrace)
+
+const enterScreen = "\u001b[?1049h\u001b[?25l"
+const leaveScreen = "\u001b[?25h\u001b[?1049l"
+const home = "\u001b[H\u001b[2J"
+const pollInterval = Duration.millis(500)
+const replayGapCap = 2_000
+
+const draw = (state: TreeState, view: TreeView, output: WatchOutput, height?: number): string =>
+  renderTree(state, {
+    width: Math.max(90, output.columns() ?? 90),
+    colour: output.colour,
+    view,
+    ...(height === undefined ? {} : { height })
+  }).join("\n")
+
+/** A full-screen frame: no taller than the terminal. */
+const drawScreen = (state: TreeState, view: TreeView, output: WatchOutput): string =>
+  draw(state, view, output, output.rows())
+
+export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function* (
+  options: WatchOptions,
+  dependencies: WatchDependencies
+): Effect.fn.Return<void, FlowError | WatchTargetMissing> {
+  const target = yield* resolveTarget(options, dependencies)
+  const { files, output } = dependencies
+  const fold = (inputs: ReadonlyArray<TreeInput>): Effect.Effect<TreeState, FlowError> =>
+    Effect.map(startingTree(target, files), (start) => inputs.reduce(reduceTree, start))
+
+  if (!output.interactive) {
+    const state = yield* Effect.flatMap(readInputs(target, files), fold)
+    return yield* output.write(`${draw(state, initialView, output)}\n`)
+  }
+
+  yield* Effect.scoped(
+    Effect.gen(function* () {
+      const keys = yield* Queue.unbounded<string>()
+      yield* Effect.forkScoped(
+        Stream.runForEach(dependencies.keys, (key) => Queue.offer(keys, key))
+      )
+      const view = yield* Ref.make<TreeView>(initialView)
+      const all = yield* readInputs(target, files)
+      // Replay steps through the inputs on their timestamps; otherwise the
+      // whole trace is shown and re-read while the run goes on.
+      const shown = yield* Ref.make(options.replay === true ? Math.min(1, all.length) : all.length)
+      const inputs = yield* Ref.make(all)
+      const speed = Math.max(1, options.speed ?? 10)
+
+      /** Waits for a key or for `wait`; true when the key was `q`. */
+      const awaitKey = (wait: Duration.Duration): Effect.Effect<boolean> =>
+        Effect.raceFirst(
+          Effect.flatMap(Queue.take(keys), (key) =>
+            Effect.gen(function* () {
+              const state = yield* Effect.orDie(
+                Effect.flatMap(Ref.get(inputs), (current) =>
+                  Effect.flatMap(Ref.get(shown), (count) => fold(current.slice(0, count)))
+                )
+              )
+              const next = onTreeKey(yield* Ref.get(view), key, state)
+              if (next === "quit") {
+                return true
+              }
+              yield* Ref.set(view, next)
+              return false
+            })
+          ),
+          Effect.as(Effect.sleep(wait), false)
+        )
+
+      yield* output.write(enterScreen)
+      yield* Effect.gen(function* () {
+        while (true) {
+          const current = yield* Ref.get(inputs)
+          const count = yield* Ref.get(shown)
+          const state = yield* fold(current.slice(0, count))
+          yield* output.write(`${home}${drawScreen(state, yield* Ref.get(view), output)}`)
+          const replaying = options.replay === true && count < current.length
+          const gap = replaying
+            ? Math.min(replayGapCap, (current[count]?.at ?? 0) - (current[count - 1]?.at ?? 0)) /
+              speed
+            : Duration.toMillis(pollInterval)
+          if (yield* awaitKey(Duration.millis(Math.max(0, gap)))) {
+            return
+          }
+          if (replaying) {
+            yield* Ref.update(shown, (shownCount) => shownCount + 1)
+          } else if (state.ended === undefined) {
+            const reread = yield* readInputs(target, files)
+            yield* Ref.set(inputs, reread)
+            yield* Ref.set(shown, reread.length)
+          }
+        }
+      }).pipe(Effect.ensuring(output.write(leaveScreen)))
+    })
+  )
+})
+
+// ── node wiring ─────────────────────────────────────────────────────────────
+
+const nodeListEpics = (directory: string): ReadonlyArray<string> =>
+  existsSync(directory)
+    ? readdirSync(directory).filter((name) => statSync(join(directory, name)).isDirectory())
+    : []
+
+export const nodeWatchDependencies = (
+  environment: Readonly<Record<string, string | undefined>> = process.env
+): WatchDependencies => {
+  const interactive = process.stdout.isTTY === true && process.stdin.isTTY === true
+  return {
+    files: nodePlainFileStore,
+    listTraces: nodeListTraces,
+    listEpics: nodeListEpics,
+    output: {
+      write: (text) => Effect.sync(() => void process.stdout.write(text)),
+      columns: () => process.stdout.columns,
+      rows: () => process.stdout.rows,
+      interactive,
+      colour: process.stdout.isTTY === true && environment.NO_COLOR === undefined
+    },
+    keys: nodeTreeKeys("detach")
+  }
+}