@llm4ts/flow 2.45.0 → 2.46.0

package/src/OperatorSchemas.ts

@@ -0,0 +1,221 @@
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+import { AuthStatus, Availability } from "@llm4ts/core/Models"
+import { BoardStatus } from "./BoardSync.ts"
+import { CostReport } from "./CostReport.ts"
+import { RunOutcome } from "./FlowRecorder.ts"
+import { StoryStatus } from "./Stories.ts"
+
+/** Where a run the operator started stands, as the registry last recorded it. */
+export const OperatorRunState = Schema.Literals([
+  "starting",
+  "running",
+  "exited",
+  "interrupted",
+  "lost"
+])
+export type OperatorRunState = typeof OperatorRunState.Type
+
+/** The typed knobs a client may set when it starts a run; every one is optional. */
+export const OperatorKnobs = Schema.Struct({
+  task: Schema.optionalKey(Schema.String),
+  epic: Schema.optionalKey(Schema.String),
+  pack: Schema.optionalKey(Schema.String),
+  executors: Schema.optionalKey(Schema.Array(Schema.String)),
+  coder: Schema.optionalKey(Schema.String),
+  judgeRounds: Schema.optionalKey(Schema.Int),
+  mergeRevisions: Schema.optionalKey(Schema.Int),
+  /** The branch to land. */
+  land: Schema.optionalKey(Schema.String),
+  flags: Schema.optionalKey(Schema.Array(Schema.String)),
+  requestId: Schema.optionalKey(Schema.String)
+})
+export type OperatorKnobs = typeof OperatorKnobs.Type
+
+/** One registry record: a run the operator started, appended on every state change. */
+export class OperatorRun extends Schema.Class<OperatorRun>("OperatorRun")({
+  runId: Schema.String,
+  repo: Schema.String,
+  flow: Schema.String,
+  args: Schema.Array(Schema.String),
+  knobs: OperatorKnobs,
+  startedAt: Schema.Number,
+  pid: Schema.optionalKey(Schema.Int),
+  tracePath: Schema.optionalKey(Schema.String),
+  logDir: Schema.String,
+  state: OperatorRunState,
+  exitCode: Schema.optionalKey(Schema.Int),
+  signal: Schema.optionalKey(Schema.String),
+  endedAt: Schema.optionalKey(Schema.Number),
+  requestId: Schema.optionalKey(Schema.String)
+}) {}
+
+export const decodeOperatorRunLine = Schema.decodeUnknownOption(Schema.fromJsonString(OperatorRun))
+export const encodeOperatorRunLine = Schema.encodeSync(Schema.fromJsonString(OperatorRun))
+
+/** The last record per run, newest `startedAt` first; a line that does not decode is skipped. */
+export const latestRuns = (lines: ReadonlyArray<string>): ReadonlyArray<OperatorRun> => {
+  const byRun = new Map<string, OperatorRun>()
+  for (const line of lines) {
+    if (line.trim().length === 0) continue
+    for (const run of Option.toArray(decodeOperatorRunLine(line))) byRun.set(run.runId, run)
+  }
+  return [...byRun.values()].sort((a, b) => b.startedAt - a.startedAt)
+}
+
+export const LaneStatusOut = Schema.Struct({
+  id: Schema.String,
+  status: Schema.Literals(["running", "done", "failed"]),
+  stage: Schema.optionalKey(Schema.String),
+  executor: Schema.optionalKey(Schema.String),
+  activity: Schema.optionalKey(Schema.String),
+  lastEventAgeMs: Schema.Int,
+  costUsd: Schema.Number
+})
+export type LaneStatusOut = typeof LaneStatusOut.Type
+
+export class RunStatus extends Schema.Class<RunStatus>("RunStatus")({
+  runId: Schema.String,
+  state: OperatorRunState,
+  ended: Schema.optionalKey(RunOutcome),
+  elapsedMs: Schema.Int,
+  lanes: Schema.Array(LaneStatusOut),
+  stories: Schema.Array(Schema.Struct({ id: Schema.String, status: BoardStatus })),
+  tokens: Schema.Int,
+  costUsd: Schema.Number,
+  warnings: Schema.Array(Schema.String),
+  seq: Schema.Int,
+  summary: Schema.String
+}) {}
+
+export const MeaningfulEvent = Schema.Struct({
+  seq: Schema.Int,
+  at: Schema.Number,
+  kind: Schema.String,
+  lane: Schema.optionalKey(Schema.String),
+  text: Schema.String
+})
+export type MeaningfulEvent = typeof MeaningfulEvent.Type
+
+export class RunWaitResult extends Schema.Class<RunWaitResult>("RunWaitResult")({
+  events: Schema.Array(MeaningfulEvent),
+  seq: Schema.Int,
+  ended: Schema.optionalKey(RunOutcome),
+  exited: Schema.Boolean,
+  summary: Schema.String
+}) {}
+
+export const ConnectorHealthOut = Schema.Struct({
+  id: Schema.String,
+  availability: Availability,
+  authStatus: AuthStatus,
+  // "auth": the CLI's own login check answered; "version": only `--version`
+  // ran, which proves no live login; "unknown": nothing more can be said.
+  probe: Schema.Literals(["version", "auth", "unknown"]),
+  latencyMs: Schema.optionalKey(Schema.Int)
+})
+export type ConnectorHealthOut = typeof ConnectorHealthOut.Type
+
+export const ExecutorHealthOut = Schema.Struct({
+  id: Schema.String,
+  harness: Schema.String,
+  roles: Schema.Array(Schema.String),
+  disabled: Schema.Boolean,
+  healthy: Schema.optionalKey(Schema.Boolean)
+})
+export type ExecutorHealthOut = typeof ExecutorHealthOut.Type
+
+export class PreflightResult extends Schema.Class<PreflightResult>("PreflightResult")({
+  llm4ts: Schema.String,
+  node: Schema.String,
+  connectors: Schema.Array(ConnectorHealthOut),
+  executors: Schema.Array(ExecutorHealthOut),
+  notes: Schema.Array(Schema.String)
+}) {}
+
+export class StoryDetail extends Schema.Class<StoryDetail>("StoryDetail")({
+  id: Schema.String,
+  title: Schema.String,
+  state: Schema.optionalKey(
+    Schema.Struct({
+      status: StoryStatus,
+      branch: Schema.String,
+      worktree: Schema.String,
+      executor: Schema.optionalKey(Schema.String)
+    })
+  ),
+  board: Schema.optionalKey(
+    Schema.Struct({ status: BoardStatus, detail: Schema.optionalKey(Schema.String) })
+  ),
+  tasks: Schema.Array(Schema.Struct({ title: Schema.String, completed: Schema.Boolean })),
+  findings: Schema.optionalKey(Schema.String),
+  verdict: Schema.optionalKey(Schema.Json),
+  gateLogs: Schema.Array(Schema.String)
+}) {}
+
+export class Diagnosis extends Schema.Class<Diagnosis>("Diagnosis")({
+  runId: Schema.String,
+  story: Schema.optionalKey(Schema.String),
+  digest: Schema.String,
+  failure: Schema.optionalKey(
+    Schema.Struct({
+      stage: Schema.optionalKey(Schema.String),
+      message: Schema.String,
+      lane: Schema.optionalKey(Schema.String)
+    })
+  ),
+  gateLogTails: Schema.Array(Schema.Struct({ path: Schema.String, tail: Schema.String })),
+  transcriptTail: Schema.Array(Schema.String)
+}) {}
+
+export class CostsOut extends Schema.Class<CostsOut>("CostsOut")({
+  report: CostReport,
+  /** The run's cost: its trace, topped up from its ledger line where the trace was short. */
+  total: Schema.Number,
+  ledger: Schema.optionalKey(Schema.Number),
+  /** USD the ledger line supplied beyond the trace, when the trace lost lines. */
+  fromLedger: Schema.optionalKey(Schema.Number),
+  /** The trace says more than the ledger line, which no line can fill. */
+  differs: Schema.Boolean
+}) {}
+
+export class UnknownRepo extends Schema.TaggedError<UnknownRepo>()("UnknownRepo", {
+  message: Schema.String
+}) {}
+
+export class UnknownRun extends Schema.TaggedError<UnknownRun>()("UnknownRun", {
+  message: Schema.String
+}) {}
+
+export class UnknownStory extends Schema.TaggedError<UnknownStory>()("UnknownStory", {
+  message: Schema.String
+}) {}
+
+export class UnknownFlow extends Schema.TaggedError<UnknownFlow>()("UnknownFlow", {
+  message: Schema.String
+}) {}
+
+export class NotAllowed extends Schema.TaggedError<NotAllowed>()("NotAllowed", {
+  message: Schema.String
+}) {}
+
+/** A start knob that would reach the flow's argv or environment in an unsafe shape. */
+export class InvalidKnob extends Schema.TaggedError<InvalidKnob>()("InvalidKnob", {
+  knob: Schema.String,
+  message: Schema.String
+}) {}
+
+export class RunInProgress extends Schema.TaggedError<RunInProgress>()("RunInProgress", {
+  message: Schema.String,
+  runId: Schema.String
+}) {}
+
+/** An epic id that is not a folder under the repository's `.llm4ts/epics/`. */
+export class UnknownEpic extends Schema.TaggedError<UnknownEpic>()("UnknownEpic", {
+  message: Schema.String
+}) {}
+
+/** A state file that exists but could not be read or parsed; the message names its path. */
+export class ReadFailed extends Schema.TaggedError<ReadFailed>()("ReadFailed", {
+  message: Schema.String
+}) {}

package/src/Retro.ts

@@ -431,6 +431,17 @@ const runLinePrefixes = [
   "retro:"
 ]
 
+/** One story's digest section, whatever its outcome; `undefined` when the plan has no such story. */
+export const renderStoryDigest = (
+  inputs: RetroInputs,
+  storyId: string,
+  share: number = perStoryShare
+): string | undefined => {
+  const trace = traceView(inputs.trace)
+  const entry = inputs.stories.find((candidate) => candidate.story.id === storyId)
+  return entry === undefined ? undefined : storySection(inputs, trace, entry, share)
+}
+
 /** The digest a retro seat is given: code-built, deterministic, capped. */
 export const renderRetroDigest = (inputs: RetroInputs): string => {
   const trace = traceView(inputs.trace)

package/src/Review.ts

@@ -19,7 +19,14 @@ import {
   type FlowError
 } from "./FlowError.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
-import { GateBaseline, gateIssuePrefix, isGateIssue, triageGates } from "./GateTriage.ts"
+import {
+  GateBaseline,
+  describeGateReason,
+  gateIssuePrefix,
+  isGateIssue,
+  testGateReasonOf,
+  triageGates
+} from "./GateTriage.ts"
 import {
   type OracleRules,
   checkOracle,
@@ -75,6 +82,8 @@ export class ReviewIssue extends Schema.Class<ReviewIssue>("ReviewIssue")({
   origin: Schema.optionalKey(Schema.Literals(["new", "base", "flaky"])),
   /** How a gate ended: a red exit, killed at the timeout, or a signal exit. */
   gateClass: Schema.optionalKey(Schema.Literals(["red", "hang", "crash"])),
+  /** Why a test gate's output could not stand for green: no tests ran, or test files failed to load. */
+  gateReason: Schema.optionalKey(Schema.Literals(["zero-tests", "load-failure"])),
   /** Where the gate's full output was written, when the caller asked for a log. */
   logPath: Schema.optionalKey(Schema.String)
 }) {}
@@ -538,7 +547,11 @@ export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function
       )
     )
   )
-  const failed = result === undefined || result.exitCode !== 0
+  const output = result === undefined ? "" : [...result.stdout, ...result.stderr].join("\n")
+  // A runner that collected nothing, or whose files failed to load, is red
+  // whatever it exited with: a green exit over zero tests proves nothing.
+  const reason = result === undefined ? undefined : testGateReasonOf(output)
+  const failed = result === undefined || result.exitCode !== 0 || reason !== undefined
   yield* events.publish(
     Timed.make({
       kind: "gate",
@@ -550,16 +563,15 @@ export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function
   )
   let logPath: string | undefined
   if (options.log !== undefined) {
-    const output =
-      result === undefined ? "" : [...result.stdout, ...result.stderr].join("\n").trim()
-    yield* options.log.files.writeAtomic(options.log.path, output)
+    yield* options.log.files.writeAtomic(options.log.path, output.trim())
     logPath = options.log.path
   }
+  // No summary line to count and a reason not to trust the run: zero passed.
   const passed =
     result === undefined
       ? undefined
-      : passedCountIn([...result.stdout, ...result.stderr].join("\n"))
-  if (result !== undefined && result.exitCode === 0) {
+      : (passedCountIn(output) ?? (reason === undefined ? undefined : 0))
+  if (!failed) {
     return ReviewResult.make({
       issues: [],
       summary: "lint passed",
@@ -568,16 +580,18 @@ export const lintCommand = Effect.fn("@llm4ts/flow/Review.lintCommand")(function
   }
   const seconds =
     options.timeout === undefined ? 0 : Math.round(Duration.toSeconds(options.timeout))
+  const problem =
+    result === undefined
+      ? `gate killed: no exit after ${seconds} seconds (LLM4TS_GATE_TIMEOUT)`
+      : processProblem(result.stdout, result.stderr, result.exitCode)
   return ReviewResult.make({
     issues: [
       ReviewIssue.make({
         severity: "Critical",
         title: `${gateIssuePrefix}${label}`,
-        description:
-          result === undefined
-            ? `gate killed: no exit after ${seconds} seconds (LLM4TS_GATE_TIMEOUT)`
-            : processProblem(result.stdout, result.stderr, result.exitCode),
+        description: reason === undefined ? problem : `${describeGateReason(reason)}\n\n${problem}`,
         gateClass: result === undefined ? "hang" : gateClassOf(result.exitCode),
+        ...(reason === undefined ? {} : { gateReason: reason }),
         ...(logPath === undefined ? {} : { logPath })
       })
     ],

package/src/RunState.ts

@@ -0,0 +1,72 @@
+// The run's own state lives under `<repo>/.llm4ts/`: traces, the cost
+// ledger, plans, transcripts, epics. It belongs to the machine the run
+// happened on, not to the repository: a committed trace is read by every
+// reviewer at real cost, and a coder that reaches it can wipe an earlier
+// run. So the first write under a `.llm4ts/` directory leaves a
+// `.gitignore` there that ignores everything, and a flow commit never
+// stages the directory (see `GitTool.commitAll`).
+import * as Effect from "effect/Effect"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+
+/** The directory name, as a path segment. */
+export const RunStateDirectory = ".llm4ts"
+
+/** What `<dir>/.llm4ts/.gitignore` holds: everything under it is ignored. */
+export const runStateIgnoreContents = "*\n"
+
+/**
+ * The glob every CLI seat is denied by default (ADR 0027 amendment,
+ * 2026-10-22): the run state, relative to the seat's working directory.
+ */
+export const runStateDeniedPaths: ReadonlyArray<string> = [`${RunStateDirectory}/**`]
+
+const ignoreName = ".gitignore"
+
+/**
+ * The `<dir>/.llm4ts` prefix of `path` when the path has a `.llm4ts`
+ * segment; the first such segment, so a worktree nested under the run
+ * state (`.llm4ts/port/shards/1/.llm4ts/…`) still ignores the outer one
+ * first. Separators are kept as written.
+ */
+export const runStateRootOf = (path: string): string | undefined => {
+  const match = /^(.*?)(^|[\\/])\.llm4ts(?=[\\/]|$)/.exec(path)
+  return match === null ? undefined : `${match[1] ?? ""}${match[2] ?? ""}${RunStateDirectory}`
+}
+
+/**
+ * The store with one rule on top: the first write under any `.llm4ts/`
+ * directory creates its `.gitignore` (`*`) when none exists, so nothing
+ * the run writes there is ever staged. An ignore file the repository
+ * already has is left as it is: a team that commits its own flows or
+ * forked packs keeps its exceptions. Idempotent to wrap twice.
+ */
+export const ignoringRunState = (store: PlainFileStoreShape): PlainFileStoreShape => {
+  const ensured = new Set<string>()
+  const ensureIgnore = (path: string): Effect.Effect<void, never> => {
+    const root = runStateRootOf(path)
+    if (root === undefined || ensured.has(root)) {
+      return Effect.void
+    }
+    const separator = root.includes("\\") && !root.includes("/") ? "\\" : "/"
+    const ignorePath = `${root}${separator}${ignoreName}`
+    if (path === ignorePath) {
+      return Effect.void
+    }
+    return store.read(ignorePath).pipe(
+      Effect.flatMap((existing) =>
+        existing === undefined ? store.writeAtomic(ignorePath, runStateIgnoreContents) : Effect.void
+      ),
+      // A store that cannot write the ignore file is about to fail the
+      // write itself, with its own error; nothing to add here.
+      Effect.catch(() => Effect.void),
+      Effect.tap(() => Effect.sync(() => void ensured.add(root)))
+    )
+  }
+  return {
+    ...store,
+    writeAtomic: (path, contents) =>
+      ensureIgnore(path).pipe(Effect.andThen(store.writeAtomic(path, contents))),
+    append: (path, contents) =>
+      ensureIgnore(path).pipe(Effect.andThen(store.append(path, contents)))
+  }
+}