@llm4ts/flow 2.45.0 → 2.47.0

package/src/GateTriage.ts

@@ -16,6 +16,97 @@ export type GateClass = typeof GateClass.Type
 export const FailureOrigin = Schema.Literals(["new", "base", "flaky"])
 export type FailureOrigin = typeof FailureOrigin.Type
 
+/**
+ * Why a test gate's exit code proves nothing: the runner collected or ran
+ * zero tests, or test files failed to load (an import that no longer
+ * resolves, a suite that errors before its first test). Either makes the
+ * gate red whatever the runner's exit code was.
+ */
+export const GateReason = Schema.Literals(["zero-tests", "load-failure"])
+export type GateReason = typeof GateReason.Type
+
+// One suite that errored before its tests ran, per runner: Vitest's
+// "Failed Suites", Jest's "Test suite failed to run", pytest's collection
+// errors, JUnit's class initialisation error under Surefire.
+const loadFailureMarkers: ReadonlyArray<RegExp> = [
+  /Failed Suites\s+\d+/u,
+  /Test suite failed to run/u,
+  /\berrors? during collection\b/u,
+  /ExceptionInInitializerError|initializationError/u
+]
+const vitestNoTests = /\bTests\s+no tests\b/u
+const vitestFilesFailed = /\bTest Files\s+\d+ failed\b/u
+// Nothing collected: Vitest, Jest, pytest, Surefire, Gradle.
+const zeroTestsMarkers: ReadonlyArray<RegExp> = [
+  /No test files found/u,
+  vitestNoTests,
+  /No tests found, exiting with code/u,
+  /\bTests:\s+0 total\b/u,
+  /\bno tests ran\b/u,
+  /\bcollected 0 items\b/u,
+  /No tests to run\./u,
+  /No tests found for given includes/u
+]
+const cargoRunning = /\brunning (\d+) tests?\b/gu
+const junitRun = /\bTests run:\s*(\d+)/gu
+const mochaPassing = /^\s*0 passing\b/mu
+const mochaFailing = /^\s*\d+ failing\b/mu
+
+const everyCountZero = (pattern: RegExp, output: string): boolean => {
+  let seen = false
+  pattern.lastIndex = 0
+  for (let match = pattern.exec(output); match !== null; match = pattern.exec(output)) {
+    seen = true
+    if (Number.parseInt(match[1] ?? "0", 10) > 0) {
+      return false
+    }
+  }
+  return seen
+}
+
+/**
+ * The reason a test runner's output cannot stand for a green gate, when
+ * it has one: `load-failure` when any suite errored before its tests ran
+ * (it wins, since a load failure also leaves tests unrun), `zero-tests`
+ * when the runner collected nothing (Vitest, Jest, pytest, cargo test,
+ * mocha, JUnit via Maven or Gradle). `undefined` means tests ran.
+ */
+export const testGateReasonOf = (output: string): GateReason | undefined => {
+  if (loadFailureMarkers.some((pattern) => pattern.test(output))) {
+    return "load-failure"
+  }
+  if (vitestNoTests.test(output) && vitestFilesFailed.test(output)) {
+    return "load-failure"
+  }
+  if (zeroTestsMarkers.some((pattern) => pattern.test(output))) {
+    return "zero-tests"
+  }
+  if (everyCountZero(cargoRunning, output) || everyCountZero(junitRun, output)) {
+    return "zero-tests"
+  }
+  if (mochaPassing.test(output) && !mochaFailing.test(output)) {
+    return "zero-tests"
+  }
+  return undefined
+}
+
+/** The reason as the fix prompt and the findings read it. */
+export const describeGateReason = (reason: GateReason): string =>
+  reason === "zero-tests"
+    ? "test gate ran zero tests (zero-tests): the runner collected no test, so its exit code proves nothing"
+    : "test files failed to load (load-failure): a suite errored before its tests ran, so the gate is red whatever its exit code"
+
+/**
+ * The reason as a failing line, so a baseline records it and triage
+ * compares it like any other line: a target whose base already ran zero
+ * tests inherits that, a change that breaks loading is charged with it.
+ */
+export const gateReasonLine = (reason: GateReason): string => `gate reason: ${reason}`
+
+/** The first gate reason a result carries, if any. */
+export const gateReasonOf = (result: ReviewResult): GateReason | undefined =>
+  result.issues.find((issue) => isGateIssue(issue) && issue.gateReason !== undefined)?.gateReason
+
 export class GateBaseline extends Schema.Class<GateBaseline>("GateBaseline")({
   baseCommit: Schema.String,
   appDir: Schema.String,
@@ -87,17 +178,22 @@ const legacyGateIssuePrefix = "lint failed: "
 export const isGateIssue = (issue: ReviewIssue): boolean =>
   issue.title.startsWith(gateIssuePrefix) || issue.title.startsWith(legacyGateIssuePrefix)
 
+/** A gate issue's comparable lines: its reason first, then its normalized output. */
+const failingLinesOfIssue = (
+  issue: ReviewIssue,
+  roots: ReadonlyArray<string>
+): ReadonlyArray<string> => [
+  ...(issue.gateReason === undefined ? [] : [gateReasonLine(issue.gateReason)]),
+  ...normalizeGateOutput(issue.description, roots)
+]
+
 /** Every gate issue's normalized failing lines, in order, each once. */
 export const failingLinesOf = (
   result: ReviewResult,
   roots: ReadonlyArray<string>
 ): ReadonlyArray<string> =>
   Array.from(
-    new Set(
-      result.issues
-        .filter(isGateIssue)
-        .flatMap((issue) => normalizeGateOutput(issue.description, roots))
-    )
+    new Set(result.issues.filter(isGateIssue).flatMap((issue) => failingLinesOfIssue(issue, roots)))
   )
 
 export interface GateTriage {
@@ -134,18 +230,28 @@ export const triageGates = (
       issues.push(issue)
       continue
     }
-    const lines = normalizeGateOutput(issue.description, roots)
+    const lines = failingLinesOfIssue(issue, roots)
     const fresh = lines.filter((line) => !known.has(line))
     inherited.push(...lines.filter((line) => known.has(line)))
     if (lines.length > 0 && fresh.length === 0) {
       continue
     }
     newLines.push(...fresh)
+    // A fresh reason keeps its sentence, so the fix prompt says what the
+    // runner's output meant, not only which lines were new.
+    const reasonLine = issue.gateReason === undefined ? undefined : gateReasonLine(issue.gateReason)
+    const freshOutput = fresh.filter((line) => line !== reasonLine)
+    const description =
+      issue.gateReason !== undefined && fresh.includes(reasonLine ?? "")
+        ? [describeGateReason(issue.gateReason), ...freshOutput].join("\n")
+        : fresh.length > 0
+          ? fresh.join("\n")
+          : issue.description
     issues.push(
       ReviewIssue.make({
         ...issue,
         origin: "new",
-        description: fresh.length > 0 ? fresh.join("\n") : issue.description
+        description
       })
     )
   }

package/src/GitTool.ts

@@ -6,6 +6,7 @@ import { MergeConflict, ProcessError, type FlowError } from "./FlowError.ts"
 import { Began, Timed, type FlowEventsShape } from "./FlowEvents.ts"
 import { timeEffect } from "./Timing.ts"
 import { guarded } from "./CapabilityGuard.ts"
+import { RunStateDirectory } from "./RunState.ts"
 
 export class BranchCreated extends Schema.TaggedClass<BranchCreated>()("Created", {}) {}
 export class BranchAlreadyExists extends Schema.TaggedClass<BranchAlreadyExists>()(
@@ -149,15 +150,20 @@ const problem = (result: ProcessResult): string => {
 }
 
 /**
- * The runner's own bookkeeping under `workDir/.llm4ts/`: the run trace and
- * the cost ledger. `commitAll` never stages them — they grow while the run
- * commits and belong to the machine, not the repository — while the rest of
- * `.llm4ts/` (plans, forked packs) is committed as before.
+ * The run's own state under `workDir/.llm4ts/`: traces, the cost ledger,
+ * plans, transcripts, epics. `commitAll` never stages it — it grows while
+ * the run commits and belongs to the machine, not the repository (a
+ * committed trace was read by every reviewer at real cost). `commitPaths`
+ * stages exactly what it is given, so a flow that keeps something there on
+ * purpose (a forked pack, a port ledger) names it.
  */
-export const runnerBookkeeping: ReadonlyArray<string> = [
-  ".llm4ts/trace-*.jsonl",
-  ".llm4ts/costs.jsonl"
-]
+export const runStatePaths: ReadonlyArray<string> = [RunStateDirectory]
+
+/** Whether a repository-relative path is the run state or inside it. */
+export const isRunStatePath = (path: string): boolean => {
+  const normalized = path.replaceAll("\\", "/").replace(/^\.\//u, "")
+  return normalized === RunStateDirectory || normalized.startsWith(`${RunStateDirectory}/`)
+}
 
 export const makeGitTool = (
   process: ProcessExecutorShape,
@@ -277,12 +283,14 @@ export const makeGitTool = (
   const checkout = (name: string): Effect.Effect<void, FlowError> =>
     write("git checkout", runOrFail(["checkout", name]).pipe(Effect.asVoid))
 
-  // Stage everything, then take the runner's bookkeeping back out of the
-  // index: `reset -- <glob>` leaves an ignored or unmatched glob alone and
-  // keeps a previously committed trace at its HEAD version, whereas an
-  // `:(exclude)` pathspec makes `add` refuse the ignored files outright.
+  // Stage everything, then take the run state back out of the index:
+  // `reset -- <path>` leaves an ignored or missing path alone and keeps a
+  // previously committed plan or trace at its HEAD version (so neither its
+  // change nor its deletion is staged), whereas an `:(exclude)` pathspec
+  // makes `add` refuse the ignored files outright. The `.gitignore` the
+  // runner leaves there (`RunState`) already keeps new files out of `add`.
   const addAll = runOrFail(["add", "-A"]).pipe(
-    Effect.andThen(runOrFail(["reset", "-q", "--", ...runnerBookkeeping])),
+    Effect.andThen(runOrFail(["reset", "-q", "--", ...runStatePaths])),
     Effect.asVoid
   )
 
@@ -294,9 +302,15 @@ export const makeGitTool = (
       }
       // "nothing to commit, working tree clean" when the tree is clean;
       // "nothing added to commit but untracked files present" when the only
-      // changes are files this commit was not asked to stage.
+      // changes are files this commit was not asked to stage; "no changes
+      // added to commit" when the only changes are to tracked files it was
+      // not asked to stage (a plan under the run state, revised by the run).
       const detail = problem(result)
-      if (detail.includes("nothing to commit") || detail.includes("nothing added to commit")) {
+      if (
+        detail.includes("nothing to commit") ||
+        detail.includes("nothing added to commit") ||
+        detail.includes("no changes added to commit")
+      ) {
         return new NothingToCommit()
       }
       return yield* ProcessError.make({
@@ -311,13 +325,27 @@ export const makeGitTool = (
   // `add -A -- <paths>` stages additions, modifications, AND deletions of
   // exactly those paths; a plain `add` would refuse a deleted file. `--only`
   // on commit would also work but ignores paths that were never tracked.
+  // A path under the run state is force-added: it is wanted (a forked
+  // pack, a port ledger) where the runner's own ignore file would refuse
+  // it. Any other path keeps the repository's ignore rules.
   const commitPathsEffect = (
     message: string,
     paths: ReadonlyArray<string>
-  ): Effect.Effect<CommitResult, FlowError> =>
-    paths.length === 0
+  ): Effect.Effect<CommitResult, FlowError> => {
+    const underRunState = paths.filter(isRunStatePath)
+    const elsewhere = paths.filter((path) => !isRunStatePath(path))
+    return paths.length === 0
       ? Effect.succeed(new NothingToCommit())
-      : runOrFail(["add", "-A", "--", ...paths]).pipe(Effect.andThen(commitStaged(message)))
+      : Effect.gen(function* () {
+          if (elsewhere.length > 0) {
+            yield* runOrFail(["add", "-A", "--", ...elsewhere])
+          }
+          if (underRunState.length > 0) {
+            yield* runOrFail(["add", "-A", "-f", "--", ...underRunState])
+          }
+          return yield* commitStaged(message)
+        })
+  }
 
   return {
     init: write(

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)))
+  }
+}