@llm4ts/flow 2.7.0 → 2.8.0

package/src/FlowError.ts

@@ -168,11 +168,40 @@ export class MissingDependency extends Schema.TaggedError<MissingDependency>()(
 export class MergeConflict extends Schema.TaggedError<MergeConflict>()("MergeConflict", {
   branch: Schema.String,
   into: Schema.String,
-  paths: Schema.Array(Schema.String)
+  paths: Schema.Array(Schema.String),
+  /** What git said when no path is in conflict — a merge refused before it started. */
+  detail: Schema.optionalKey(Schema.String)
 }) {
   get message(): string {
-    const where = this.paths.length === 0 ? "" : `: ${this.paths.join(", ")}`
-    return `merging '${this.branch}' into '${this.into}' conflicted${where}`
+    if (this.paths.length > 0) {
+      return `merging '${this.branch}' into '${this.into}' conflicted: ${this.paths.join(", ")}`
+    }
+    const why = this.detail === undefined || this.detail.length === 0 ? "" : `: ${this.detail}`
+    return `merging '${this.branch}' into '${this.into}' failed${why}`
+  }
+}
+
+/**
+ * The epic checkout holds changes no story may make there — a coder worked
+ * outside its worktree. Every later merge and epic gate would inherit them,
+ * so the executor stops launching stories until an operator cleans it.
+ */
+export class EpicCheckoutDirty extends Schema.TaggedError<EpicCheckoutDirty>()(
+  "EpicCheckoutDirty",
+  {
+    checkout: Schema.String,
+    paths: Schema.Array(Schema.String),
+    /** The story that had just finished when the change was found. */
+    story: Schema.optionalKey(Schema.String)
+  }
+) {
+  get message(): string {
+    const suspect = this.story === undefined ? "" : ` (found after story '${this.story}' finished)`
+    return [
+      `the epic checkout ${this.checkout} has uncommitted changes${suspect} — a coder worked outside its worktree:`,
+      ...this.paths.map((path) => `- ${path}`),
+      "Move each change into the owning story's worktree or discard it, then rerun."
+    ].join("\n")
   }
 }
 
@@ -240,6 +269,7 @@ export const FlowError = Schema.Union([
   PerimeterViolation,
   MissingDependency,
   MergeConflict,
+  EpicCheckoutDirty,
   StoryFailed,
   DecisionsInvalid,
   OpenPointsPending,

package/src/FlowEvents.ts

@@ -1,5 +1,7 @@
 import * as Context from "effect/Context"
+import type * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
 import * as Layer from "effect/Layer"
 import * as PubSub from "effect/PubSub"
 import * as Ref from "effect/Ref"
@@ -177,9 +179,16 @@ export const makeFlowEventHub = Effect.fn("@llm4ts/flow/FlowEvents.makeHub")(fun
   const events = yield* PubSub.bounded<FlowEvent>(capacity)
   const published = yield* Ref.make(0)
   return {
+    // Counted AFTER delivery, and only when the PubSub accepted the event.
+    // Tallying first meant a publish interrupted while backpressured (a
+    // bounded PubSub suspends when a subscriber is behind) left `published`
+    // permanently above anything a consumer could ever reach, and every
+    // drain waiting on it never finished.
     publish: (event) =>
-      Ref.update(published, (count) => count + 1).pipe(
-        Effect.andThen(PubSub.publish(events, event)),
+      PubSub.publish(events, event).pipe(
+        Effect.flatMap((accepted) =>
+          accepted ? Ref.update(published, (count) => count + 1) : Effect.void
+        ),
         Effect.asVoid
       ),
     subscribe: PubSub.subscribe(events),
@@ -187,3 +196,34 @@ export const makeFlowEventHub = Effect.fn("@llm4ts/flow/FlowEvents.makeHub")(fun
     publishedCount: Ref.get(published)
   }
 })
+
+/** How long a consumer waits to catch up before the run moves on regardless. */
+export const defaultDrainTimeout = "3 seconds"
+
+/**
+ * The shared drain: wait until `consumed` has caught up with everything the
+ * hub published, and report whether it did.
+ *
+ * Bounded on purpose, and the single copy of this loop. A consumer can fall
+ * permanently short of the count — a subscription torn down early, an
+ * event the PubSub refused — and an unbounded wait then pegs a core forever.
+ * In the runner that swallowed the end of a run: every stage printed and
+ * ticked green, and no cost summary ever following, because the summary is
+ * written only once every consumer reports drained.
+ */
+export const awaitConsumed = (
+  hub: FlowEventHub,
+  consumed: Ref.Ref<number>,
+  timeout: Duration.Input = defaultDrainTimeout
+): Effect.Effect<boolean> =>
+  Effect.gen(function* () {
+    const target = yield* hub.publishedCount
+    const drain: Effect.Effect<void> = Effect.suspend(() =>
+      Ref.get(consumed).pipe(
+        Effect.flatMap((count) =>
+          count >= target ? Effect.void : Effect.yieldNow.pipe(Effect.andThen(drain))
+        )
+      )
+    )
+    return Option.isSome(yield* Effect.timeoutOption(drain, timeout))
+  })

package/src/FlowRecorder.ts

@@ -1,4 +1,5 @@
 import * as Clock from "effect/Clock"
+import type * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
@@ -7,7 +8,7 @@ import type * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
 import type { StreamRecorder } from "@llm4ts/core/observability/StreamRecorder"
 import type { JsonValue } from "@llm4ts/core/providers/CliSupport"
-import type { FlowEvent, FlowEventHub } from "./FlowEvents.ts"
+import { awaitConsumed, type FlowEvent, type FlowEventHub } from "./FlowEvents.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
 
 export class TraceLine extends Schema.Class<TraceLine>("TraceLine")({
@@ -24,7 +25,8 @@ export interface FlowRecorderShape extends StreamRecorder {
   readonly tracePath: string
   readonly record: (event: FlowEvent) => Effect.Effect<void>
   readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
-  readonly awaitDrained: (hub: FlowEventHub) => Effect.Effect<void>
+  /** Waits for this recorder to catch up; `false` means it gave up first. */
+  readonly awaitDrained: (hub: FlowEventHub, timeout?: Duration.Input) => Effect.Effect<boolean>
 }
 
 const encode = (line: TraceLine): string =>
@@ -99,18 +101,7 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
           Effect.asVoid
         )
       }),
-    awaitDrained: (hub) =>
-      Effect.gen(function* () {
-        const target = yield* hub.publishedCount
-        const drain: Effect.Effect<void> = Effect.suspend(() =>
-          Ref.get(consumed).pipe(
-            Effect.flatMap((count) =>
-              count >= target ? Effect.void : Effect.yieldNow.pipe(Effect.andThen(drain))
-            )
-          )
-        )
-        yield* drain
-      })
+    awaitDrained: (hub, timeout) => awaitConsumed(hub, consumed, timeout)
   }
   return recorder
 })

package/src/GitTool.ts

@@ -24,6 +24,11 @@ export interface GitToolShape {
   readonly initBare: Effect.Effect<void, FlowError>
   readonly config: (key: string, value: string) => Effect.Effect<void, FlowError>
   readonly status: Effect.Effect<string, FlowError>
+  /**
+   * Every path with uncommitted changes, untracked files listed one by one
+   * (not collapsed into their directory), minus the runner's `.llm4ts/`.
+   */
+  readonly uncommittedFiles: Effect.Effect<ReadonlyArray<string>, FlowError>
   readonly currentBranch: Effect.Effect<string, FlowError>
   readonly diff: Effect.Effect<string, FlowError>
   readonly diffAll: Effect.Effect<string, FlowError>
@@ -66,6 +71,16 @@ export interface GitToolShape {
   ) => Effect.Effect<void, FlowError>
   /** `force` also removes a worktree holding untracked or modified files. */
   readonly removeWorktree: (path: string, force?: boolean) => Effect.Effect<void, FlowError>
+  /** Moves an existing worktree to `to`, keeping its branch and uncommitted work. */
+  readonly moveWorktree: (from: string, to: string) => Effect.Effect<void, FlowError>
+  /**
+   * Puts `paths` back as they are on `source`: a path `source` has is checked
+   * out from it, a path it lacks is deleted (tracked or not). Uncommitted.
+   */
+  readonly restorePaths: (
+    source: string,
+    paths: ReadonlyArray<string>
+  ) => Effect.Effect<void, FlowError>
   readonly branchExists: (name: string) => Effect.Effect<boolean, FlowError>
   readonly deleteBranch: (name: string) => Effect.Effect<void, FlowError>
   /** Whether `commit` is reachable from `of` — a merged story branch is an ancestor of the epic head. */
@@ -73,11 +88,41 @@ export interface GitToolShape {
   /**
    * Merges `branch` into the checked-out branch with a merge commit. A
    * conflict fails typed with the conflicting paths and leaves the tree as it
-   * was (the merge is aborted), so the next merge can proceed.
+   * was (the merge is aborted), so the next merge can proceed. A merge git
+   * refuses before it starts (a dirty tree) fails typed with git's words.
+   * `preferIncoming` resolves conflicting hunks to `branch`'s side
+   * (`-X theirs`): the catch-up of a story branch with its epic, where the
+   * epic side is authoritative for every path the story does not own.
    */
-  readonly merge: (branch: string, message: string) => Effect.Effect<void, FlowError>
+  readonly merge: (
+    branch: string,
+    message: string,
+    options?: MergeOptions
+  ) => Effect.Effect<void, FlowError>
+}
+
+export interface MergeOptions {
+  readonly preferIncoming?: boolean
 }
 
+/**
+ * The paths `git status --short` reports, minus the runner's own state under
+ * `.llm4ts/`. A rename reports its destination.
+ */
+export const statusPaths = (status: string): ReadonlyArray<string> =>
+  status
+    .split(/\r?\n/)
+    .filter((line) => line.trim().length > 0)
+    .map((line) => {
+      // `status` trims its output, so the first line may have lost the
+      // leading blank of its two-letter code: match the code, not a column.
+      const path = (/^[ MADRCTU?!]{1,2}\s+(.+)$/.exec(line)?.[1] ?? "").trim()
+      const arrow = path.indexOf(" -> ")
+      const target = arrow < 0 ? path : path.slice(arrow + 4)
+      return target.replace(/^"|"$/g, "")
+    })
+    .filter((path) => path.length > 0 && !path.startsWith(".llm4ts/") && path !== ".llm4ts")
+
 const nonInteractiveEnvironment = Object.freeze({
   GIT_TERMINAL_PROMPT: "0",
   GIT_SSH_COMMAND: "ssh -o BatchMode=yes"
@@ -265,6 +310,10 @@ export const makeGitTool = (
     config: (key, value) =>
       write("git config", runOrFail(["config", key, value]).pipe(Effect.asVoid)),
     status: read("git status", runOrFail(["status", "--short"])),
+    uncommittedFiles: read(
+      "git uncommittedFiles",
+      runOrFail(["status", "--porcelain", "--untracked-files=all"]).pipe(Effect.map(statusPaths))
+    ),
     currentBranch: read("git currentBranch", runOrFail(["rev-parse", "--abbrev-ref", "HEAD"])),
     diff: read("git diff", runOrFail(["diff"])),
     diffAll: read(
@@ -328,6 +377,39 @@ export const makeGitTool = (
         "git worktree add -b",
         runOrFail(["worktree", "add", "-b", branch, path, startPoint]).pipe(Effect.asVoid)
       ),
+    moveWorktree: (from, to) =>
+      write(
+        "git worktree move",
+        Effect.gen(function* () {
+          // git creates a new worktree's parents but not a moved one's.
+          const parent = to.replace(/[\\/]+$/, "").replace(/[\\/][^\\/]*$/, "")
+          if (parent.length > 0 && parent !== to) {
+            yield* process
+              .run(["mkdir", "-p", parent], workDir, nonInteractiveEnvironment)
+              .pipe(
+                Effect.mapError((error) =>
+                  ProcessError.make({ message: `mkdir -p ${parent}`, detail: error.message })
+                )
+              )
+          }
+          yield* runOrFail(["worktree", "move", from, to])
+        })
+      ),
+    restorePaths: (source, paths) =>
+      write(
+        "git restorePaths",
+        Effect.gen(function* () {
+          for (const path of paths) {
+            const known = yield* run(["cat-file", "-e", `${source}:${path}`])
+            if (known.exitCode === 0) {
+              yield* runOrFail(["checkout", source, "--", path])
+            } else {
+              yield* runOrFail(["rm", "-r", "-f", "-q", "--ignore-unmatch", "--", path])
+              yield* runOrFail(["clean", "-f", "-d", "-q", "--", path])
+            }
+          }
+        })
+      ),
     removeWorktree: (path, force = false) =>
       write(
         "git worktree remove",
@@ -356,11 +438,18 @@ export const makeGitTool = (
                 )
         )
       ),
-    merge: (branch, message) =>
+    merge: (branch, message, options = {}) =>
       write(
         "git merge",
         Effect.gen(function* () {
-          const result = yield* run(["merge", "--no-ff", "-m", message, branch])
+          const result = yield* run([
+            "merge",
+            "--no-ff",
+            ...(options.preferIncoming === true ? ["-X", "theirs"] : []),
+            "-m",
+            message,
+            branch
+          ])
           if (result.exitCode === 0) {
             return
           }
@@ -374,7 +463,12 @@ export const makeGitTool = (
           // next story; a merge that failed before starting has nothing to
           // abort and git says so, which is not a second failure.
           yield* run(["merge", "--abort"])
-          return yield* MergeConflict.make({ branch, into, paths })
+          return yield* MergeConflict.make({
+            branch,
+            into,
+            paths,
+            ...(paths.length === 0 ? { detail: problem(result) } : {})
+          })
         })
       )
   }

package/src/JudgmentLog.ts

@@ -1,11 +1,12 @@
 import * as Clock from "effect/Clock"
+import type * as Duration from "effect/Duration"
 import * as Effect from "effect/Effect"
 import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import * as Semaphore from "effect/Semaphore"
 import type * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
-import { JudgmentObserved, type FlowEvent, type FlowEventHub } from "./FlowEvents.ts"
+import { awaitConsumed, JudgmentObserved, type FlowEvent, type FlowEventHub } from "./FlowEvents.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
 
 export class JudgmentObservation extends Schema.Class<JudgmentObservation>("JudgmentObservation")({
@@ -29,7 +30,8 @@ export const judgmentLogPath = (root: string, consumer: JudgmentObservation["con
 export interface JudgmentLogShape {
   readonly record: (event: FlowEvent) => Effect.Effect<void>
   readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
-  readonly awaitDrained: (hub: FlowEventHub) => Effect.Effect<void>
+  /** Waits for this log to catch up; `false` means it gave up first. */
+  readonly awaitDrained: (hub: FlowEventHub, timeout?: Duration.Input) => Effect.Effect<boolean>
 }
 
 const codec = Schema.fromJsonString(JudgmentObservation)
@@ -63,18 +65,8 @@ export const makeJudgmentLog = Effect.fn("@llm4ts/flow/JudgmentLog.make")(functi
           }).pipe(Effect.catch(() => Ref.set(degraded, true)))
         )
 
-  const awaitDrained = (hub: FlowEventHub): Effect.Effect<void> =>
-    Effect.gen(function* () {
-      const target = yield* hub.publishedCount
-      const drain: Effect.Effect<void> = Effect.suspend(() =>
-        Ref.get(consumed).pipe(
-          Effect.flatMap((count) =>
-            count >= target ? Effect.void : Effect.yieldNow.pipe(Effect.andThen(drain))
-          )
-        )
-      )
-      yield* drain
-    })
+  const awaitDrained = (hub: FlowEventHub, timeout?: Duration.Input): Effect.Effect<boolean> =>
+    awaitConsumed(hub, consumed, timeout)
 
   return {
     record,

package/src/Perimeter.ts

@@ -3,7 +3,16 @@
 // the prompt states the rule, this is what makes it true.
 import * as Effect from "effect/Effect"
 import { PerimeterViolation } from "./FlowError.ts"
-import { pathWithin, type Story } from "./StoryPlan.ts"
+import type { Task } from "./Plan.ts"
+import { ReviewIssue, ReviewResult } from "./Review.ts"
+import {
+  normalizePath,
+  ownerOf,
+  pathWithin,
+  pathsNamedIn,
+  type Story,
+  type StoryPlan
+} from "./StoryPlan.ts"
 
 export interface PerimeterCheck {
   /** Changed paths under a `sharedReadOnly` prefix — the worse class, reported first. */
@@ -47,3 +56,78 @@ export const enforcePerimeter = Effect.fn("@llm4ts/flow/Perimeter.enforce")(func
     })
   }
 })
+
+/**
+ * The perimeter as a gate result: a violation is one Critical issue whose
+ * text names every stray path, so the task review loop hands it back to the
+ * coder to revert before anything is committed.
+ */
+export const perimeterGate = (changedPaths: ReadonlyArray<string>, story: Story): ReviewResult => {
+  const check = checkPerimeter(changedPaths, story)
+  if (isWithinPerimeter(check)) {
+    return ReviewResult.make({ issues: [], summary: "perimeter: clean" })
+  }
+  const violation = PerimeterViolation.make({
+    story: story.id,
+    outside: check.outside,
+    sharedReadOnly: check.sharedReadOnly
+  })
+  return ReviewResult.make({
+    issues: [
+      ReviewIssue.make({
+        severity: "Critical",
+        title: "perimeter",
+        description: [
+          violation.message,
+          "Revert these paths (restore a changed file from the epic branch, delete a file you",
+          "created there) and keep the work inside your owned paths."
+        ].join("\n")
+      })
+    ],
+    summary: "perimeter: violated"
+  })
+}
+
+/** A planned task that names paths outside its story's perimeter. */
+export interface StrayTask {
+  readonly task: Task
+  readonly paths: ReadonlyArray<string>
+  /** Some of `paths` are owned by another story — the task is that story's work. */
+  readonly foreign: boolean
+}
+
+const fileLike = /\.[A-Za-z0-9]{1,5}$/
+
+const allowed = (story: Story, path: string): boolean =>
+  story.owned.some((prefix) => pathWithin(path, prefix)) ||
+  story.sharedReadOnly.some((prefix) => pathWithin(path, prefix)) ||
+  // A bare directory above an owned path ("inside src/features/conto") is a
+  // location, not a target.
+  (!fileLike.test(normalizePath(path)) && story.owned.some((prefix) => pathWithin(prefix, path)))
+
+/**
+ * The incomplete tasks of a story's plan that name paths the story may not
+ * touch. Checked before any coder turn is spent on them: a task such as
+ * "register the screen in src/App.tsx" is another story's job.
+ */
+export const strayTasks = (
+  plan: StoryPlan,
+  story: Story,
+  tasks: ReadonlyArray<Task>
+): ReadonlyArray<StrayTask> =>
+  tasks.flatMap((task) => {
+    if (task.completed) {
+      return []
+    }
+    const paths = pathsNamedIn(plan, `${task.title}\n${task.description}`).filter(
+      (path) => !allowed(story, path)
+    )
+    if (paths.length === 0) {
+      return []
+    }
+    const foreign = paths.some((path) => {
+      const owner = ownerOf(plan, path)
+      return owner !== undefined && owner.id !== story.id
+    })
+    return [{ task, paths, foreign }]
+  })