@llm4ts/flow 2.45.0 → 2.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm4ts/flow",
-  "version": "2.45.0",
+  "version": "2.46.0",
   "description": "Effect-native LLM workflow, persistence, review, and repository automation",
   "license": "MIT",
   "type": "module",
@@ -38,6 +38,7 @@
     "./Domains": "./dist/Domains.js",
     "./EpicBrief": "./dist/EpicBrief.js",
     "./EpicRuns": "./dist/EpicRuns.js",
+    "./OperatorSchemas": "./dist/OperatorSchemas.js",
     "./Equiv": "./dist/Equiv.js",
     "./EquivReport": "./dist/EquivReport.js",
     "./EstimatedUsage": "./dist/EstimatedUsage.js",
@@ -71,6 +72,7 @@
     "./OracleGuard": "./dist/OracleGuard.js",
     "./Orientation": "./dist/Orientation.js",
     "./Persistence": "./dist/Persistence.js",
+    "./RunState": "./dist/RunState.js",
     "./Plan": "./dist/Plan.js",
     "./PlanExecution": "./dist/PlanExecution.js",
     "./Port": "./dist/Port.js",
@@ -127,7 +129,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@llm4ts/core": "2.45.0"
+    "@llm4ts/core": "2.46.0"
   },
   "peerDependencies": {
     "effect": "4.0.0"

package/src/Approval.ts

@@ -28,6 +28,12 @@ export class MissingModernizeArtifact extends Schema.TaggedError<MissingModerniz
 export const ApprovedMarker = "- [x] Approved"
 export const DraftApprovalMarker = "- [ ] Approved"
 
+/** `- [ ] Approved` → `- [x] Approved` in a markdown document; unchanged when already approved. */
+export const approveMarkdown = (markdown: string): string =>
+  markdown.includes(ApprovedMarker)
+    ? markdown
+    : markdown.replace(DraftApprovalMarker, ApprovedMarker)
+
 export const withDraftApproval = (markdown: string): string =>
   `${markdown.trimEnd()}\n\n${DraftApprovalMarker}\n`
 

package/src/AutonomyContract.ts

@@ -17,6 +17,12 @@ const workspace = [
   "files only where your instructions name them. What it expects of you is in your instructions."
 ]
 
+const runState = [
+  "The directory `.llm4ts/` at the root of your working directory is the run's own state — traces,",
+  "plans, transcripts and costs that belong to the tool running you. Never read, modify, delete or",
+  "commit anything under it; the one exception is a path there that your instructions name as yours."
+]
+
 const noGaming = [
   "Never edit, skip, delete or weaken a test to make a gate pass. A test you believe is wrong is a",
   "finding to report, not a line to change; a pre-existing bug outside your task is a finding, not",
@@ -41,8 +47,8 @@ const evidence = [
 
 /**
  * The contract for a profile. `full` is the default; `minimal` keeps scope,
- * the workspace rule and the no-gaming rule for a model that over-verifies
- * under the full text;
+ * the workspace rule, the run-state rule and the no-gaming rule for a model
+ * that over-verifies under the full text;
  * `off` is the empty string, for a flow that writes its own rules.
  */
 export const autonomyContract = (profile: ContractProfile = "full"): string => {
@@ -50,12 +56,13 @@ export const autonomyContract = (profile: ContractProfile = "full"): string => {
     case "off":
       return ""
     case "minimal":
-      return [...scope, ...workspace, ...noGaming].join("\n")
+      return [...scope, ...workspace, ...runState, ...noGaming].join("\n")
     case "full":
       return [
         ...unattended,
         ...scope,
         ...workspace,
+        ...runState,
         ...minimalChange,
         ...noGaming,
         ...evidence

package/src/CostReport.ts

@@ -1,7 +1,9 @@
 import * as DateTime from "effect/DateTime"
+import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
 import * as Schema from "effect/Schema"
 import type { TokenUsage } from "@llm4ts/core/Models"
+import type { CostRecord } from "./CostLedger.ts"
 import { isEstimatedModel } from "./EstimatedUsage.ts"
 import { TokensUsed, cloneName } from "./FlowEvents.ts"
 import type { TraceLine } from "./FlowRecorder.ts"
@@ -16,10 +18,22 @@ import { estimateCostUsd, PricesAsOf } from "./PriceList.ts"
  * backend's own token counts) and estimated usage (`EstimatedUsage`'s
  * character-count fallback, labelled `estimated:<model>`) are kept in separate
  * columns so a budget never mistakes one for the other.
+ *
+ * The trace is the source for timing, the cost ledger (`CostLedger`) for the
+ * run's total: both come from the same `TokensUsed` events, but the trace is
+ * a file in the target's working tree that a coder's shell, a `git clean`
+ * or a recorder that lost its disk can shorten, while the ledger line is
+ * written once from the run's own cost tracker, the same numbers the run
+ * printed. `reconcileWithLedger` tops a short trace up from its ledger line,
+ * so `llm4ts costs` and the run's summary agree.
  */
 
 export const UnknownModel = "(unknown)"
 
+/** Where a sample's numbers came from: a trace line, or the run's ledger line filling a short trace. */
+export const UsageSource = Schema.Literals(["trace", "ledger"])
+export type UsageSource = typeof UsageSource.Type
+
 export class UsageSample extends Schema.Class<UsageSample>("UsageSample")({
   /** Epoch milliseconds of the token report. */
   at: Schema.Number,
@@ -34,7 +48,11 @@ export class UsageSample extends Schema.Class<UsageSample>("UsageSample")({
   estimated: Schema.Boolean,
   /** The lane's executor and clone, when the usage came from a roster lane (ADR 0033). */
   executor: Schema.optionalKey(Schema.String),
-  clone: Schema.optionalKey(Schema.Int)
+  clone: Schema.optionalKey(Schema.Int),
+  source: UsageSource.pipe(
+    Schema.withConstructorDefault(Effect.succeed("trace" as const)),
+    Schema.withDecodingDefaultKey(Effect.succeed("trace" as const))
+  )
 }) {}
 
 export class UsageTotals extends Schema.Class<UsageTotals>("UsageTotals")({
@@ -173,7 +191,8 @@ const totalsOf = (samples: ReadonlyArray<UsageSample>): UsageTotals => {
   const cached = sumOptional(samples.map((sample) => sample.cached))
   const costUsd = sumOptional(samples.map((sample) => sample.costUsd))
   return UsageTotals.make({
-    requests: samples.length,
+    // A ledger sample is a remainder, not a call the trace saw.
+    requests: samples.filter((sample) => sample.source === "trace").length,
     prompt: samples.reduce((sum, sample) => sum + sample.prompt, 0),
     completion: samples.reduce((sum, sample) => sum + sample.completion, 0),
     total: samples.reduce((sum, sample) => sum + sample.total, 0),
@@ -182,6 +201,137 @@ const totalsOf = (samples: ReadonlyArray<UsageSample>): UsageTotals => {
   })
 }
 
+interface UsageSums {
+  prompt: number
+  completion: number
+  total: number
+  cached: number | undefined
+  costUsd: number | undefined
+}
+
+const emptySums = (): UsageSums => ({
+  prompt: 0,
+  completion: 0,
+  total: 0,
+  cached: undefined,
+  costUsd: undefined
+})
+
+const addSums = (into: UsageSums, usage: UsageSums): UsageSums => ({
+  prompt: into.prompt + usage.prompt,
+  completion: into.completion + usage.completion,
+  total: into.total + usage.total,
+  cached: sumOptional([into.cached, usage.cached]),
+  costUsd: sumOptional([into.costUsd, usage.costUsd])
+})
+
+const positive = (value: number): number => (value > 0 ? value : 0)
+
+/** What `b` has beyond `a`, per field, never below zero. */
+const remainderOf = (ledger: UsageSums, trace: UsageSums): UsageSums => ({
+  prompt: positive(ledger.prompt - trace.prompt),
+  completion: positive(ledger.completion - trace.completion),
+  total: positive(ledger.total - trace.total),
+  cached: ledger.cached === undefined ? undefined : positive(ledger.cached - (trace.cached ?? 0)),
+  costUsd:
+    ledger.costUsd === undefined ? undefined : positive(ledger.costUsd - (trace.costUsd ?? 0))
+})
+
+const hasRemainder = (sums: UsageSums): boolean =>
+  sums.prompt > 0 ||
+  sums.completion > 0 ||
+  sums.total > 0 ||
+  (sums.cached ?? 0) > 0 ||
+  (sums.costUsd ?? 0) > 1e-9
+
+interface UsageRow {
+  readonly agent: string
+  readonly model: string
+  readonly prompt: number
+  readonly completion: number
+  readonly total: number
+  readonly cached?: number
+  readonly costUsd?: number
+}
+
+/** A run's sums per agent and model, from its trace samples or its ledger cells. */
+const sumsByAgentModel = (
+  rows: ReadonlyArray<UsageRow>
+): ReadonlyMap<
+  string,
+  { readonly agent: string; readonly model: string; readonly sums: UsageSums }
+> => {
+  const groups = new Map<string, { agent: string; model: string; sums: UsageSums }>()
+  for (const row of rows) {
+    const key = JSON.stringify([row.agent, row.model])
+    const group = groups.get(key) ?? { agent: row.agent, model: row.model, sums: emptySums() }
+    groups.set(key, {
+      ...group,
+      sums: addSums(group.sums, {
+        prompt: row.prompt,
+        completion: row.completion,
+        total: row.total,
+        cached: row.cached,
+        costUsd: row.costUsd
+      })
+    })
+  }
+  return groups
+}
+
+export interface LedgerReconciliation {
+  readonly samples: ReadonlyArray<UsageSample>
+  /** Runs whose ledger line carried usage the trace did not: filled, in ledger order. */
+  readonly filledRuns: ReadonlyArray<string>
+}
+
+/**
+ * Tops the trace's samples up from the ledger: for every ledger record, what
+ * its cells hold beyond the trace's samples of that run, per agent and
+ * model, becomes one `ledger` sample at the run's start (the only time the
+ * ledger knows). A run with no trace at all is taken wholly from its line;
+ * a run whose trace matches its line adds nothing. The result's total
+ * therefore equals the ledger's, which is what the run itself printed.
+ */
+export const reconcileWithLedger = (
+  samples: ReadonlyArray<UsageSample>,
+  records: ReadonlyArray<CostRecord>
+): LedgerReconciliation => {
+  const filled: Array<UsageSample> = []
+  const filledRuns: Array<string> = []
+  for (const record of records) {
+    const traced = sumsByAgentModel(samples.filter((sample) => sample.runId === record.runId))
+    const ledgered = sumsByAgentModel(record.cells)
+    let filledThisRun = false
+    for (const [key, { agent, model, sums }] of ledgered) {
+      const remainder = remainderOf(sums, traced.get(key)?.sums ?? emptySums())
+      if (!hasRemainder(remainder)) {
+        continue
+      }
+      filledThisRun = true
+      filled.push(
+        UsageSample.make({
+          at: Date.parse(record.at),
+          runId: record.runId,
+          agent,
+          model,
+          prompt: remainder.prompt,
+          completion: remainder.completion,
+          total: remainder.total,
+          ...(remainder.cached === undefined ? {} : { cached: remainder.cached }),
+          ...(remainder.costUsd === undefined ? {} : { costUsd: remainder.costUsd }),
+          estimated: isEstimatedModel(model),
+          source: "ledger"
+        })
+      )
+    }
+    if (filledThisRun) {
+      filledRuns.push(record.runId)
+    }
+  }
+  return { samples: [...samples, ...filled], filledRuns }
+}
+
 const distinctRuns = (samples: ReadonlyArray<UsageSample>): number =>
   new Set(samples.map((sample) => sample.runId)).size
 

package/src/FlowRecorder.ts

@@ -24,9 +24,18 @@ export class TraceLine extends Schema.Class<TraceLine>("TraceLine")({
 export const RunOutcome = Schema.Literals(["completed", "failed", "interrupted"])
 export type RunOutcome = typeof RunOutcome.Type
 
+/** Lines the recorder could not write: the trace is short by this much, from the first failure on. */
+export interface TraceShortfall {
+  readonly lines: number
+  /** The first write failure, as the file store described it. */
+  readonly reason: string
+}
+
 export interface FlowRecorderShape extends StreamRecorder {
   readonly runId: string
   readonly tracePath: string
+  /** What the trace is missing, once a write failed; `undefined` while every line landed. */
+  readonly shortfall: Effect.Effect<TraceShortfall | undefined>
   readonly record: (event: FlowEvent) => Effect.Effect<void>
   readonly consume: (hub: FlowEventHub) => Effect.Effect<void, never, Scope.Scope>
   /** Appends the `RunEnded` line: a reader knows the run is over, not stalled. */
@@ -53,12 +62,18 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
   const sequence = yield* Ref.make(0)
   const consumed = yield* Ref.make(0)
   const lock = yield* Semaphore.make(1)
-  const degraded = yield* Ref.make(false)
+  // Set by the first failed write and never cleared: a disk that refused one
+  // line is not asked again, but every line it then loses is counted, so
+  // the run can say how short its trace is (`llm4ts costs` reads the
+  // ledger for the rest).
+  const degraded = yield* Ref.make<TraceShortfall | undefined>(undefined)
 
   const append = (kind: string, fields: Readonly<Record<string, JsonValue>>): Effect.Effect<void> =>
     lock.withPermit(
       Effect.gen(function* () {
-        if (yield* Ref.get(degraded)) {
+        const shortfall = yield* Ref.get(degraded)
+        if (shortfall !== undefined) {
+          yield* Ref.set(degraded, { ...shortfall, lines: shortfall.lines + 1 })
           return
         }
         const seq = yield* Ref.getAndUpdate(sequence, (current) => current + 1)
@@ -73,7 +88,7 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
         })
         yield* files
           .append(tracePath, `${encode(line)}\n`)
-          .pipe(Effect.catch(() => Ref.set(degraded, true)))
+          .pipe(Effect.catch((error) => Ref.set(degraded, { lines: 1, reason: error.message })))
       })
     )
 
@@ -83,6 +98,7 @@ export const makeFlowRecorder = Effect.fn("@llm4ts/flow/FlowRecorder.make")(func
   const recorder: FlowRecorderShape = {
     runId,
     tracePath,
+    shortfall: Ref.get(degraded),
     record,
     rawLine: (provider, model, line) =>
       append("RawLine", {

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(