@llm4ts/runner 2.44.1 → 2.46.0

package/src/RunReaders.ts

@@ -0,0 +1,413 @@
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { Board, BoardVersion } from "@llm4ts/flow/BoardSync"
+import { loadCostLedger } from "@llm4ts/flow/CostLedger"
+import {
+  buildCostReport,
+  reconcileWithLedger,
+  usageSamplesFromTrace
+} from "@llm4ts/flow/CostReport"
+import { describeFlowError, type FlowError } from "@llm4ts/flow/FlowError"
+import { FlowEvent } from "@llm4ts/flow/FlowEvents"
+import { RunOutcome, type TraceLine } from "@llm4ts/flow/FlowRecorder"
+import {
+  CostsOut,
+  Diagnosis,
+  RunStatus,
+  type LaneStatusOut,
+  type MeaningfulEvent,
+  type OperatorRunState
+} from "@llm4ts/flow/OperatorSchemas"
+import { loadVersioned, type PlainFileStoreShape } from "@llm4ts/flow/Persistence"
+import { parsePlan } from "@llm4ts/flow/Plan"
+import { readTrace } from "@llm4ts/flow/Replay"
+import { emptyTree, reduceTree, treeInputsOfTrace, type TreeState } from "./AgentTree.ts"
+import { summarizeTree } from "./RunSummary.ts"
+import { loadTranscript, tailLinesOf, type TranscriptFiles } from "./Transcripts.ts"
+
+/**
+ * Read-only answers about a run, from the files it writes: how it stands,
+ * what happened since a sequence number, why it failed, what it cost. Every
+ * reader takes the file store as a parameter, so a test feeds it a memory
+ * store and the MCP operator feeds it the real one.
+ */
+
+export class TraceUnreadable extends Schema.TaggedError<TraceUnreadable>()("TraceUnreadable", {
+  path: Schema.String,
+  message: Schema.String
+}) {}
+
+export interface RunSources {
+  readonly files: PlainFileStoreShape
+  /**
+   * Relative paths of every regular file under a directory, recursively (e.g.
+   * "task-2/1-pnpm-test.log"), never directory names; none when it does not exist.
+   */
+  readonly listFiles: (directory: string) => ReadonlyArray<string>
+}
+
+export interface TraceFold {
+  readonly lines: ReadonlyArray<TraceLine>
+  readonly state: TreeState
+  readonly seq: number
+}
+
+const decodeEvent = Schema.decodeUnknownOption(Schema.fromJsonString(FlowEvent))
+const isOutcome = Schema.is(RunOutcome)
+
+const eventOf = (line: TraceLine): FlowEvent | undefined => {
+  const raw = line.fields.event
+  return typeof raw === "string" ? Option.getOrUndefined(decodeEvent(raw)) : undefined
+}
+
+const unreadable =
+  (path: string) =>
+  (error: FlowError): TraceUnreadable =>
+    TraceUnreadable.make({ path, message: describeFlowError(error) })
+
+const readLines = (
+  files: PlainFileStoreShape,
+  path: string
+): Effect.Effect<ReadonlyArray<TraceLine>, TraceUnreadable> =>
+  readTrace(files, path).pipe(Effect.mapError(unreadable(path)))
+
+const lastSeq = (lines: ReadonlyArray<TraceLine>): number => lines[lines.length - 1]?.seq ?? 0
+
+/** The trace folded into the watch TUI's tree, seeded from the epic's board when there is one. */
+export const foldTrace = (
+  files: PlainFileStoreShape,
+  tracePath: string,
+  boardDir?: string
+): Effect.Effect<TraceFold, TraceUnreadable> =>
+  Effect.gen(function* () {
+    const lines = yield* readLines(files, tracePath)
+    const board =
+      boardDir === undefined
+        ? undefined
+        : yield* loadVersioned(files, join(boardDir, "board.json"), BoardVersion, Board).pipe(
+            Effect.catch(() => Effect.succeed(undefined))
+          )
+    const start = emptyTree(
+      board === undefined
+        ? {}
+        : {
+            title: board.title.replace(/^Epic:\s*/u, "epic "),
+            stories: board.items.map((item) => ({ id: item.id, status: item.status }))
+          }
+    )
+    const state = treeInputsOfTrace(lines).reduce(reduceTree, start)
+    return { lines, state, seq: lastSeq(lines) }
+  })
+
+export const runStatusOf = (
+  fold: TraceFold,
+  run: {
+    readonly runId: string
+    readonly flow: string
+    readonly state: OperatorRunState
+  },
+  now: number
+): RunStatus => {
+  const { state } = fold
+  const lanes = state.lanes.map((lane): LaneStatusOut => {
+    const stage = lane.stages[lane.stages.length - 1]
+    return {
+      id: lane.id,
+      status: lane.status,
+      ...(stage === undefined ? {} : { stage }),
+      ...(lane.executor === undefined ? {} : { executor: lane.executor }),
+      ...(lane.activity === undefined ? {} : { activity: lane.activity.text }),
+      lastEventAgeMs: Math.max(0, Math.round(now - lane.lastEventAt)),
+      costUsd: lane.costUsd
+    }
+  })
+  const unenforceable = fold.lines.flatMap((line) => {
+    const event = eventOf(line)
+    return event?._tag === "CapabilityUnenforceable" ? [event.detail] : []
+  })
+  const end = state.ended === undefined ? now : (state.now ?? now)
+  return RunStatus.make({
+    runId: run.runId,
+    state: run.state,
+    ...(state.ended !== undefined && isOutcome(state.ended) ? { ended: state.ended } : {}),
+    elapsedMs: state.startedAt === undefined ? 0 : Math.max(0, Math.round(end - state.startedAt)),
+    lanes,
+    stories: state.stories.map((story) => ({ id: story.id, status: story.status })),
+    tokens: Math.round(state.tokens),
+    costUsd: state.costUsd,
+    warnings: [
+      ...unenforceable,
+      ...state.exclusions.map((entry) => `${entry.executor} excluded: ${entry.reason}`)
+    ],
+    seq: fold.seq,
+    summary: summarizeTree(state, run.flow)
+  })
+}
+
+export const meaningfulKinds: ReadonlySet<string> = new Set([
+  "StoryStatusChanged",
+  "StageFailed",
+  "Aborted",
+  "CapabilityUnenforceable",
+  "ExecutorExcluded",
+  "ExecutorHandedOver",
+  "StoryJudged",
+  "Began",
+  "RunEnded"
+])
+
+const textOf = (
+  event: FlowEvent
+): { readonly text: string; readonly lane?: string } | undefined => {
+  switch (event._tag) {
+    case "StoryStatusChanged":
+      return { text: `story ${event.id} ${event.status}`, lane: event.id }
+    case "StageFailed":
+      return {
+        text: `${event.stage} failed: ${event.message}`,
+        ...(event.lane === undefined ? {} : { lane: event.lane })
+      }
+    case "Aborted":
+      return { text: `aborted: ${event.message}` }
+    case "CapabilityUnenforceable":
+      return { text: `capability unenforceable: ${event.detail}` }
+    case "ExecutorExcluded":
+      return { text: `${event.executor} excluded: ${event.reason}` }
+    case "ExecutorHandedOver":
+      return {
+        text: `${event.from} handed over ${event.role} (${event.scope}): ${event.reason}`,
+        ...(event.label === undefined ? {} : { lane: event.label })
+      }
+    case "StoryJudged":
+      return {
+        text: `${event.lane} judged round ${event.round}: ${event.cleared ? "cleared" : `${event.issues} issues`}`,
+        lane: event.lane
+      }
+    case "Began":
+      return {
+        text: `began ${event.kind} ${event.label}`,
+        ...(event.lane === undefined ? {} : { lane: event.lane })
+      }
+    default:
+      return undefined
+  }
+}
+
+export const meaningfulEventsAfter = (
+  lines: ReadonlyArray<TraceLine>,
+  sinceSeq: number
+): ReadonlyArray<MeaningfulEvent> =>
+  lines.flatMap((line): ReadonlyArray<MeaningfulEvent> => {
+    if (line.seq <= sinceSeq || !meaningfulKinds.has(line.kind)) {
+      return []
+    }
+    if (line.kind === "RunEnded") {
+      const outcome = line.fields.outcome
+      return [
+        {
+          seq: line.seq,
+          at: line.timestamp,
+          kind: line.kind,
+          text: `run ${typeof outcome === "string" ? outcome : "completed"}`
+        }
+      ]
+    }
+    const event = eventOf(line)
+    const rendered = event === undefined ? undefined : textOf(event)
+    return rendered === undefined
+      ? []
+      : [
+          {
+            seq: line.seq,
+            at: line.timestamp,
+            kind: line.kind,
+            ...(rendered.lane === undefined ? {} : { lane: rendered.lane }),
+            text: rendered.text
+          }
+        ]
+  })
+
+export const eventsAfter = (
+  lines: ReadonlyArray<TraceLine>,
+  sinceSeq: number,
+  kinds: ReadonlyArray<string> | undefined,
+  limit: number
+): ReadonlyArray<TraceLine> =>
+  lines
+    .filter(
+      (line) =>
+        line.seq > sinceSeq && (kinds === undefined || kinds.some((kind) => kind === line.kind))
+    )
+    .slice(0, Math.max(0, limit))
+
+const digestTail = 40
+const tailRows = 30
+const tailWidth = 120
+
+const quiet = <A, E>(effect: Effect.Effect<A, E>): Effect.Effect<A | undefined> =>
+  effect.pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+const capText = (text: string, remaining: number): string => text.slice(0, Math.max(0, remaining))
+
+/** The last rows of each log in a directory, within what is left of a character budget. */
+export const tailGateLogs = (
+  sources: RunSources,
+  directory: string | undefined,
+  budget: number
+): Effect.Effect<{
+  readonly tails: ReadonlyArray<{ readonly path: string; readonly tail: string }>
+  readonly remaining: number
+}> =>
+  Effect.gen(function* () {
+    const tails: Array<{ path: string; tail: string }> = []
+    let remaining = budget
+    if (directory !== undefined) {
+      for (const name of sources.listFiles(directory)) {
+        const path = join(directory, name)
+        const text = yield* quiet(sources.files.read(path))
+        if (text === undefined || remaining <= 0) continue
+        const tail = capText(text.trimEnd().split(/\r?\n/u).slice(-tailRows).join("\n"), remaining)
+        remaining -= tail.length
+        tails.push({ path, tail })
+      }
+    }
+    return { tails, remaining }
+  })
+
+/** The last rows of one lane's transcript, capped to what is left of a character budget. */
+export const tailTranscript = (
+  sources: RunSources,
+  directory: string | undefined,
+  lane: string,
+  budget: number
+): Effect.Effect<ReadonlyArray<string>> =>
+  Effect.gen(function* () {
+    const out: Array<string> = []
+    if (directory === undefined) return out
+    let remaining = budget
+    const transcriptFiles: TranscriptFiles = {
+      read: (path) => quiet(sources.files.read(path)),
+      list: sources.listFiles
+    }
+    const entries = yield* loadTranscript(transcriptFiles, directory, { lane })
+    const rows = tailLinesOf(entries, { lane }, undefined, tailWidth, tailRows) ?? []
+    for (const row of rows) {
+      if (remaining <= 0) break
+      const kept = capText(row, remaining)
+      remaining -= kept.length
+      out.push(kept)
+    }
+    return out
+  })
+
+export const runDiagnosisOf = (
+  sources: RunSources,
+  args: {
+    readonly runId: string
+    readonly tracePath: string
+    readonly planPath: string | undefined
+    readonly transcriptsDir: string | undefined
+    readonly gateLogDir: string | undefined
+    readonly budget: number
+  }
+): Effect.Effect<Diagnosis, TraceUnreadable> =>
+  Effect.gen(function* () {
+    const lines = yield* readLines(sources.files, args.tracePath)
+    const events = lines.flatMap((line) => {
+      const event = eventOf(line)
+      return event === undefined ? [] : [event]
+    })
+    const failed = events.filter(
+      (event) => event._tag === "StageFailed" || event._tag === "Aborted"
+    )
+    const last = failed[failed.length - 1]
+    const failure =
+      last === undefined
+        ? undefined
+        : last._tag === "StageFailed"
+          ? {
+              stage: last.stage,
+              message: last.message,
+              ...(last.lane === undefined ? {} : { lane: last.lane })
+            }
+          : last._tag === "Aborted"
+            ? { message: last.message }
+            : undefined
+
+    const markdown =
+      args.planPath === undefined ? undefined : yield* quiet(sources.files.read(args.planPath))
+    const plan = markdown === undefined ? undefined : yield* quiet(parsePlan(markdown))
+    const taskLines = (plan?.tasks ?? []).map(
+      (task) => `- [${task.completed ? "x" : " "}] ${task.title}`
+    )
+    const recent = events
+      .flatMap((event) =>
+        event._tag === "Info"
+          ? [event.message]
+          : event._tag === "StageFailed"
+            ? [`${event.stage} failed: ${event.message}`]
+            : []
+      )
+      .slice(-digestTail)
+    const digest = capText([...taskLines, ...recent].join("\n"), args.budget)
+    const remaining = args.budget - digest.length
+
+    const gateTails = yield* tailGateLogs(sources, args.gateLogDir, remaining)
+    const transcript = yield* tailTranscript(
+      sources,
+      args.transcriptsDir,
+      "run",
+      gateTails.remaining
+    )
+
+    return Diagnosis.make({
+      runId: args.runId,
+      digest,
+      ...(failure === undefined ? {} : { failure }),
+      gateLogTails: gateTails.tails,
+      transcriptTail: transcript
+    })
+  })
+
+const ledgerTolerance = 0.005
+
+const costOf = (report: {
+  readonly measured: { readonly costUsd?: number }
+  readonly estimated: { readonly costUsd?: number }
+}): number => (report.measured.costUsd ?? 0) + (report.estimated.costUsd ?? 0)
+
+/**
+ * One run's costs: its trace folded and topped up from its `costs.jsonl`
+ * line (`CostReport.reconcileWithLedger`), so `total` is what the run itself
+ * printed even when the trace lost lines; `fromLedger` is how much of it the
+ * ledger supplied. `differs` is left for a trace that says more than the
+ * ledger, which no line can fill.
+ */
+export const costsOfRun = (
+  files: PlainFileStoreShape,
+  tracePath: string,
+  ledgerPath: string,
+  runId: string
+): Effect.Effect<CostsOut, TraceUnreadable> =>
+  Effect.gen(function* () {
+    const lines = yield* readLines(files, tracePath)
+    const traced = usageSamplesFromTrace(lines)
+    const records = yield* loadCostLedger(files, ledgerPath).pipe(
+      Effect.mapError(unreadable(ledgerPath))
+    )
+    const record = records.find((candidate) => candidate.runId === runId)
+    const reconciled = record === undefined ? traced : reconcileWithLedger(traced, [record]).samples
+    const report = buildCostReport(reconciled)
+    const total = costOf(report)
+    const fromLedger = total - costOf(buildCostReport(traced))
+    const ledger = record?.totalCostUsd
+    return CostsOut.make({
+      report,
+      total,
+      ...(ledger === undefined ? {} : { ledger }),
+      ...(fromLedger > ledgerTolerance ? { fromLedger } : {}),
+      differs: ledger !== undefined && Math.abs(total - ledger) > ledgerTolerance
+    })
+  })

package/src/RunSummary.ts

@@ -0,0 +1,62 @@
+import type { TreeLane, TreeState } from "./AgentTree.ts"
+
+/**
+ * One sentence on how a run is going, for a chat agent that asked. Pure over
+ * the watch TUI's folded state, so a live run and a replay read the same.
+ */
+
+const listed = 3
+
+const elapsedOf = (state: TreeState): string => {
+  const minutes =
+    state.startedAt === undefined || state.now === undefined
+      ? 0
+      : Math.max(0, Math.floor((state.now - state.startedAt) / 60_000))
+  return minutes < 60 ? `${minutes} min` : `${Math.floor(minutes / 60)} h ${minutes % 60} min`
+}
+
+/** At most three entries; the rest collapse into `+<n>`. */
+const capped = (items: ReadonlyArray<string>, separator: string): string =>
+  items.length > listed
+    ? [...items.slice(0, listed), `+${items.length - listed}`].join(separator)
+    : items.join(separator)
+
+const doing = (lane: TreeLane | undefined): string =>
+  lane?.stages[lane.stages.length - 1] ?? lane?.activity?.text ?? "starting"
+
+const lastLogOf = (state: TreeState, id: string): string => {
+  for (let index = state.log.length - 1; index >= 0; index--) {
+    const entry = state.log[index]
+    if (entry !== undefined && entry.who === id) return entry.what
+  }
+  return "failed"
+}
+
+const parenthesized = (items: ReadonlyArray<string>, separator: string): string =>
+  items.length === 0 ? "" : ` (${capped(items, separator)})`
+
+export const summarizeTree = (state: TreeState, flow: string | undefined): string => {
+  const ended = state.ended === undefined ? "" : `${state.ended}, `
+  const head = `${ended}${flow ?? state.title}, ${elapsedOf(state)}`
+  const cost = `$${state.costUsd.toFixed(2)}`
+  const board = state.stories.length > 0
+  if (!board && state.lanes.length === 0) return `${head}: no stories yet, ${cost}`
+  const ids = (status: "done" | "active" | "failed"): ReadonlyArray<string> =>
+    board
+      ? state.stories.filter((story) => story.status === status).map((story) => story.id)
+      : state.lanes
+          .filter((lane) => lane.status === (status === "active" ? "running" : status))
+          .map((lane) => lane.id)
+  const active = ids("active")
+  const failed = ids("failed")
+  const activeItems = active.map((id) => {
+    const lane = state.lanes.find((open) => open.id === id)
+    return `${id}, ${lane?.executor ?? "?"}, ${doing(lane)}`
+  })
+  const failedItems = failed.map((id) => `${id}: ${lastLogOf(state, id)}`)
+  return (
+    `${head}: ${ids("done").length} stories done, ` +
+    `${active.length} active${parenthesized(activeItems, "; ")}, ` +
+    `${failed.length} failed${parenthesized(failedItems, "; ")}, ${cost}`
+  )
+}

package/src/StoryReaders.ts

@@ -0,0 +1,157 @@
+import { join } from "node:path"
+import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { describeFlowError, type FlowError } from "@llm4ts/flow/FlowError"
+import { Diagnosis, StoryDetail, UnknownStory } from "@llm4ts/flow/OperatorSchemas"
+import {
+  loadEpicFiles,
+  loadStoryFiles,
+  renderStoryDigest,
+  type RetroInputs
+} from "@llm4ts/flow/Retro"
+import { readTrace } from "@llm4ts/flow/Replay"
+import { makeStoryPlanStore, type Story, type StoryPlan } from "@llm4ts/flow/StoryPlan"
+import { TraceUnreadable, tailGateLogs, tailTranscript, type RunSources } from "./RunReaders.ts"
+import { loadTranscript, type TranscriptFiles } from "./Transcripts.ts"
+
+/**
+ * Read-only answers about one story of an epic run, from the files the story
+ * executor keeps under `<stateDir>/stories/<id>.*` and `<stateDir>/board.json`.
+ */
+
+const safeId = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u
+
+/** A story id is a file-name stem: no separators, no dots-only, nothing that climbs. */
+export const isSafeStoryId = (id: string): boolean => safeId.test(id)
+
+const decodeJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))
+const encodeJson = (value: unknown): string | undefined => JSON.stringify(value)
+
+const planPathOf = (stateDir: string): string => join(stateDir, "plan.md")
+
+const unknownStory = (storyId: string): UnknownStory =>
+  UnknownStory.make({ message: `unknown story '${storyId}'` })
+
+/** The plan's story, or `UnknownStory` for an unsafe id, a missing plan or an id the plan lacks. */
+const storyOf = (
+  sources: RunSources,
+  stateDir: string,
+  storyId: string
+): Effect.Effect<{ readonly plan: StoryPlan; readonly story: Story }, FlowError | UnknownStory> =>
+  Effect.gen(function* () {
+    if (!isSafeStoryId(storyId)) {
+      return yield* unknownStory(storyId)
+    }
+    const plan = yield* makeStoryPlanStore(sources.files).load(planPathOf(stateDir))
+    const story = plan?.story(storyId)
+    if (plan === undefined || story === undefined) {
+      return yield* unknownStory(storyId)
+    }
+    return { plan, story }
+  })
+
+export const storyDetailOf = (
+  sources: RunSources,
+  stateDir: string,
+  storyId: string
+): Effect.Effect<StoryDetail, FlowError | UnknownStory> =>
+  Effect.gen(function* () {
+    const { story } = yield* storyOf(sources, stateDir, storyId)
+    const stored = yield* loadStoryFiles(sources.files, stateDir, story)
+    const epic = yield* loadEpicFiles(sources.files, stateDir)
+    const item = epic.board?.items.find((candidate) => candidate.id === storyId)
+    const verdictText = stored.verdict === undefined ? undefined : encodeJson(stored.verdict)
+    const verdict =
+      verdictText === undefined ? undefined : Option.getOrUndefined(decodeJson(verdictText))
+    const gateDir = join(stateDir, "stories", storyId, "gates")
+    return StoryDetail.make({
+      id: story.id,
+      title: story.title,
+      ...(stored.state === undefined
+        ? {}
+        : {
+            state: {
+              status: stored.state.status,
+              branch: stored.state.branch,
+              worktree: stored.state.worktree,
+              ...(stored.state.executor === undefined ? {} : { executor: stored.state.executor })
+            }
+          }),
+      ...(item === undefined
+        ? {}
+        : {
+            board: {
+              status: item.status,
+              ...(item.detail === undefined ? {} : { detail: item.detail })
+            }
+          }),
+      tasks: (stored.plan?.tasks ?? []).map((task) => ({
+        title: task.title,
+        completed: task.completed
+      })),
+      ...(stored.findings === undefined ? {} : { findings: stored.findings }),
+      ...(verdict === undefined ? {} : { verdict }),
+      gateLogs: sources.listFiles(gateDir).map((name) => join(gateDir, name))
+    })
+  })
+
+export const storyDiagnosisOf = (
+  sources: RunSources,
+  args: {
+    readonly stateDir: string
+    readonly storyId: string
+    readonly runId: string
+    readonly tracePath: string
+    readonly transcriptsDir: string | undefined
+    readonly budget: number
+  }
+): Effect.Effect<Diagnosis, FlowError | UnknownStory | TraceUnreadable> =>
+  Effect.gen(function* () {
+    const { plan, story } = yield* storyOf(sources, args.stateDir, args.storyId)
+    const trace = yield* readTrace(sources.files, args.tracePath).pipe(
+      Effect.mapError((error) =>
+        TraceUnreadable.make({ path: args.tracePath, message: describeFlowError(error) })
+      )
+    )
+    const stored = yield* loadStoryFiles(sources.files, args.stateDir, story)
+    const epic = yield* loadEpicFiles(sources.files, args.stateDir)
+    const transcriptFiles: TranscriptFiles = {
+      read: (path) => Effect.catch(sources.files.read(path), () => Effect.succeed(undefined)),
+      list: sources.listFiles
+    }
+    const entries =
+      args.transcriptsDir === undefined
+        ? undefined
+        : yield* loadTranscript(transcriptFiles, args.transcriptsDir, { lane: story.id })
+    const inputs: RetroInputs = {
+      runId: args.runId,
+      plan,
+      trace,
+      transcripts: entries === undefined ? undefined : new Map([[story.id, entries]]),
+      report: epic.report,
+      board: epic.board,
+      stories: [stored]
+    }
+    const digest = renderStoryDigest(inputs, story.id, args.budget) ?? ""
+    const item = epic.board?.items.find((candidate) => candidate.id === story.id)
+    const gates = yield* tailGateLogs(
+      sources,
+      join(args.stateDir, "stories", story.id, "gates"),
+      args.budget - digest.length
+    )
+    const transcriptTail = yield* tailTranscript(
+      sources,
+      args.transcriptsDir,
+      story.id,
+      gates.remaining
+    )
+    return Diagnosis.make({
+      runId: args.runId,
+      story: story.id,
+      digest,
+      ...(item?.detail === undefined ? {} : { failure: { message: item.detail, lane: story.id } }),
+      gateLogTails: gates.tails,
+      transcriptTail
+    })
+  })

package/src/Terminal.ts

@@ -460,6 +460,9 @@ export const makeLiveTerminalSurface = Effect.fn("@llm4ts/runner/Terminal.makeLi
 const hideCursor = "\u001b[?25l"
 const showCursor = "\u001b[?25h"
 
+/** Re-raise only when no other listener remains to handle the signal. */
+export const shouldReraise = (otherListeners: number): boolean => otherListeners === 0
+
 /**
  * While the live status block is on screen, keystrokes must not be echoed:
  * an arrow key (or a trackpad scroll the terminal turns into one) echoes as
@@ -490,7 +493,7 @@ const quietTerminalInput = (
     // then let the signal do what it would have done.
     const onSignal = (signal: NodeJS.Signals): void => {
       restore()
-      process.kill(process.pid, signal)
+      if (shouldReraise(process.listenerCount(signal))) process.kill(process.pid, signal)
     }
     yield* Effect.sync(() => {
       stty("-echo")

package/src/Watch.ts

@@ -362,7 +362,8 @@ export const makeWatchProgram = Effect.fn("@llm4ts/runner/Watch.make")(function*
 
 // ── node wiring ─────────────────────────────────────────────────────────────
 
-const nodeListEpics = (directory: string): ReadonlyArray<string> =>
+/** Folder names under an `epics/` directory; none when it is absent. */
+export const nodeListEpics = (directory: string): ReadonlyArray<string> =>
   existsSync(directory)
     ? readdirSync(directory).filter((name) => statSync(join(directory, name)).isDirectory())
     : []