@try-works/dsh-recursive-mode 0.3.0 → 0.4.0

package/src/jobs-runner.ts

@@ -0,0 +1,222 @@
+/**
+ * T10 — track a long operation as a NATIVE job.
+ *
+ * WHY. `lintRun`, `createLinkedWorktree` and `delegateReview` run synchronously in-block,
+ * so a hung one is invisible on the board and unstoppable from it. The native registry
+ * already owns identity, lifecycle state, a bounded output ring and a kill switch; the
+ * plugin should not invent any of that, so this adapts the plugin's long operations onto
+ * `ctx.jobs` instead of building a parallel notion of "running".
+ *
+ * ⚠ AN OPTIONAL SERVICE, DEGRADED HONESTLY. `ctx.jobs` is absent in a composition that does
+ * not mount the registry. In that case the work runs DIRECTLY and the result says
+ * `tracked: false` — because failing a lint (or a worktree create) merely because no board
+ * is attached would be a worse failure than losing the progress display. The caller can
+ * always tell which happened, so "untracked" is never silently passed off as "tracked".
+ *
+ * ⚠ A CANCELLED OPERATION SETTLES `killed`, NOT `failed`. The distinction is the whole
+ * point of exposing a kill switch: "the operator stopped this" and "this broke" call for
+ * different responses, and a board that renders a deliberate kill as a failure teaches
+ * people to distrust the kill switch.
+ *
+ * ⚠ THE TIMEOUT IS A KILL, NOT A HANG. A deadline reached means the registry's `cancel` is
+ * invoked and the outcome is reported as killed with the reason — so a hung operation
+ * cannot leave a caller waiting forever on a promise nobody owns.
+ *
+ * Types are structural (the plugin's established seam style), so this module depends on the
+ * SHAPE of the registry rather than on the package, and a test can drive it with a fake
+ * without mounting the real service.
+ */
+
+/** The producer face the registry hands `run`: identity plus the ring and progress writers. */
+export interface JobHandleLike {
+  readonly id: string
+  append(text: string, options?: { stream?: string }): void
+  updateProgress(line: string): void
+}
+
+/** How a job ended. Mirrors the registry's own vocabulary verbatim. */
+export interface JobOutcomeLike {
+  status: 'completed' | 'killed' | 'failed'
+  detail?: string
+  result?: string
+}
+
+export interface JobHooksLike {
+  cancel(reason?: string): void
+  done: Promise<JobOutcomeLike>
+}
+
+export interface JobSpecLike {
+  kind: string
+  label: string
+  owner?: unknown
+  outputLimitBytes?: number
+  run(job: JobHandleLike): JobHooksLike
+}
+
+export interface JobsRegistryLike {
+  start(spec: JobSpecLike): string
+}
+
+/** What one tracked run produced. */
+export interface JobRunResult<T> {
+  /** False when no registry was available and the work ran inline. */
+  tracked: boolean
+  /** The registry-issued id, when there was one. */
+  jobId?: string
+  status: 'completed' | 'killed' | 'failed'
+  /** The terminal reason, for the board's status line. */
+  detail?: string
+  /** The operation's own value; absent when it was killed or threw. */
+  value?: T
+  /** The error message when the operation threw. */
+  error?: string
+}
+
+export interface TrackedRunOptions<T> {
+  /** Producer kind, also the id prefix: `lint`, `worktree`, `delegation`. */
+  kind: string
+  /** One-line, model-facing label. */
+  label: string
+  owner?: unknown
+  /** A deadline. Reaching it CANCELS the work rather than abandoning it. */
+  timeoutMs?: number
+  /** The work. It receives a progress reporter and an abort signal to honour. */
+  run: (context: { report: (line: string) => void; signal: AbortSignal }) => Promise<T>
+  /** Render the value into the job's terminal result line. */
+  render?: (value: T) => string
+}
+
+/** The reason used when a deadline cancelled the work. */
+export const TIMEOUT_REASON = 'timed out'
+
+/**
+ * Run `options.run` as a native job when a registry is available, inline when it is not.
+ *
+ * Never throws for a failure of the WORK: the outcome carries `status: 'failed'` and the
+ * message, because a caller tracking a job wants to read what happened rather than catch it.
+ */
+export async function runTracked<T>(
+  jobs: JobsRegistryLike | null | undefined,
+  options: TrackedRunOptions<T>,
+): Promise<JobRunResult<T>> {
+  if (jobs === null || jobs === undefined || typeof jobs.start !== 'function') {
+    // No board to report to: do the work, and SAY it was untracked.
+    try {
+      const value = await options.run({ report: () => {}, signal: new AbortController().signal })
+      return { tracked: false, status: 'completed', value }
+    } catch (err) {
+      return {
+        tracked: false,
+        status: 'failed',
+        error: err instanceof Error ? err.message : String(err),
+      }
+    }
+  }
+
+  let value: T | undefined
+  let error: string | undefined
+  // Captured from inside the synchronous starter so the caller can await it after
+  // `start` returns the id — the registry's contract is that `run` is called once,
+  // synchronously, and that its returned hooks are the only handle on the work.
+  let captured: JobHooksLike | null = null
+
+  const jobId = jobs.start({
+    kind: options.kind,
+    label: options.label,
+    ...(options.owner === undefined ? {} : { owner: options.owner }),
+    run: (job) => {
+      const controller = new AbortController()
+      const done = (async (): Promise<JobOutcomeLike> => {
+        try {
+          value = await options.run({
+            report: (line) => job.updateProgress(line),
+            signal: controller.signal,
+          })
+          return { status: 'completed', result: options.render ? options.render(value) : undefined }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err)
+          // A cancelled operation reports KILLED, not failed: the signal being aborted is how
+          // a deliberate stop reaches the work, and "stopped" is not "broken". Checked BEFORE
+          // recording an error, so a kill does not ALSO leave an `error` behind — an error
+          // field says "something broke", and carrying one beside `killed` contradicts the
+          // status a board is rendering.
+          if (controller.signal.aborted) {
+            return { status: 'killed', detail: abortReason(controller.signal) }
+          }
+          error = message
+          return { status: 'failed', detail: message }
+        }
+      })()
+      captured = {
+        cancel: (reason?: string) => {
+          // Abort first so the work can wind down, and record the reason for the outcome.
+          controller.abort(reason ?? 'cancelled')
+        },
+        done,
+      }
+      return captured
+    },
+  })
+
+  const hooks = captured as JobHooksLike | null
+  if (hooks === null) {
+    // The registry did not invoke `run`, so there is no handle on the work at all. Report
+    // it rather than pretending a job exists.
+    return { tracked: true, jobId, status: 'failed', error: 'the job registry did not start the work' }
+  }
+
+  if (options.timeoutMs === undefined) {
+    const outcome = await hooks.done
+    return { tracked: true, jobId, ...outcome, ...(value === undefined ? {} : { value }), ...(error === undefined ? {} : { error }) }
+  }
+
+  const outcome = await withDeadline(hooks, options.timeoutMs)
+  return { tracked: true, jobId, ...outcome, ...(value === undefined ? {} : { value }), ...(error === undefined ? {} : { error }) }
+}
+
+/**
+ * Await the outcome, or cancel the work and report a kill when the deadline passes.
+ *
+ * The timer is always cleared, so a completed run does not keep the process alive — a
+ * leaked timer in a long-lived plugin is a slow leak that only shows up much later.
+ */
+async function withDeadline(hooks: JobHooksLike, timeoutMs: number): Promise<JobOutcomeLike> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      hooks.done,
+      new Promise<JobOutcomeLike>((resolve) => {
+        timer = setTimeout(() => {
+          hooks.cancel(TIMEOUT_REASON)
+          // The outcome is reported here rather than awaited again: `cancel` is documented
+          // as eventually settling `done`, and a producer that ignores the signal must not
+          // be able to hold the caller hostage.
+          resolve({ status: 'killed', detail: TIMEOUT_REASON })
+        }, timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** The abort reason as a string, whatever the caller passed. Exported for a caller that
+ * turns an abort into its own action (T39 interrupts the child on a delegation kill). */
+export function abortReason(signal: AbortSignal): string {
+  const reason = (signal as unknown as { reason?: unknown }).reason
+  if (typeof reason === 'string' && reason !== '') return reason
+  return 'cancelled'
+}
+
+/**
+ * A board-facing one-liner for one run: what happened, and whether it was even tracked.
+ *
+ * Says "untracked" OUT LOUD rather than omitting the field, so a reader never has to infer
+ * from a missing id whether the job ran without a board or the board lost it.
+ */
+export function describeJobRun<T>(result: JobRunResult<T>): string {
+  const where = result.tracked ? 'job ' + (result.jobId ?? '(no id)') : 'untracked (no job registry)'
+  const why = result.detail ?? result.error
+  return result.status + ' — ' + where + (why === undefined ? '' : ': ' + why)
+}

package/src/json-safe.ts

@@ -0,0 +1,75 @@
+/**
+ * Lossless-JSON projection for tool results (FU-9 defect fix).
+ *
+ * ⚠ THE DEFECT THIS EXISTS FOR, measured live: the host refused a review result with
+ *
+ *     Error: tool "recursive_review" returned invalid output: value is not lossless JSON
+ *     ToolOutputError, code INVALID_TOOL_OUTPUT
+ *
+ * The tool returned its service result through a TYPE CAST — `return outcome as unknown as JsonValue` — and a
+ * cast is a promise the compiler cannot keep. The outcome carries live objects: the delegation's per-round
+ * `result` is whatever the host returned for a child run, which in a real session holds an Agent or a provider
+ * seam, and neither survives `JSON.stringify`.
+ *
+ * ⚠ WHY A GENERAL PROJECTION RATHER THAN STRIPPING THE KNOWN FIELD: I could delete the `result` property and
+ * pass this round's test, but the next field the engine adds would break the tool again — and the failure mode
+ * is a REFUSED RESULT, which tells the caller nothing about the work that was done. A projection that handles
+ * cycles, functions and class instances is correct for every future field rather than for this one.
+ *
+ * ⚠ AND IT IS HONEST ABOUT WHAT IT DROPS: a function becomes nothing, a cycle becomes a marker string, and a
+ * class instance becomes its own enumerable properties. Nothing is invented, and nothing silently vanishes
+ * without a trace in the output — a dropped key simply is not there, which is what "lossless JSON" means.
+ */
+import type { JsonValue } from '@deepseek-ai/dsh-util-values'
+
+/** What a reference to an already-visited object becomes, so a cycle is visible rather than dropped. */
+export const CIRCULAR_MARKER = '[circular]'
+
+/**
+ * Project any value into something `JSON.stringify` accepts, without throwing.
+ *
+ * Returns `null` for values that have no JSON form at all (a lone function, a symbol, `undefined`), which the
+ * caller decides how to present. Objects are walked by their OWN ENUMERABLE keys, so a class instance projects
+ * to its data and its methods are left behind — which is exactly what an Agent or a seam needs to become.
+ */
+export function toLosslessJson(value: unknown, seen: WeakSet<object> = new WeakSet()): JsonValue | null {
+  if (value === null) return null
+  const kind = typeof value
+  if (kind === 'string') return value as string
+  if (kind === 'boolean') return value as boolean
+  if (kind === 'number') return Number.isFinite(value as number) ? (value as number) : String(value)
+  if (kind === 'bigint') return (value as bigint).toString()
+  if (kind === 'undefined' || kind === 'function' || kind === 'symbol') return null
+
+  const object = value as object
+  if (seen.has(object)) return CIRCULAR_MARKER
+  seen.add(object)
+
+  if (Array.isArray(value)) {
+    const items: JsonValue[] = []
+    for (const item of value) {
+      const projected = toLosslessJson(item, seen)
+      // An array element with no JSON form is dropped rather than turned into null, because a null would claim
+      // the element existed and was empty.
+      if (projected !== null) items.push(projected)
+    }
+    return items
+  }
+
+  if (value instanceof Date) return value.toISOString()
+  if (value instanceof Error) return value.message
+
+  const out: Record<string, JsonValue> = {}
+  for (const key of Object.keys(object)) {
+    let raw: unknown
+    try {
+      raw = (object as Record<string, unknown>)[key]
+    } catch {
+      // A getter that throws is not a value: skip it rather than failing the whole result.
+      continue
+    }
+    const projected = toLosslessJson(raw, seen)
+    if (projected !== null) out[key] = projected
+  }
+  return out
+}

package/src/lock.ts

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
+// T17: the graph model, for the queries that are graph operations (see getPrerequisites).
+import { buildPhaseGraph, nextLegalPhase, prerequisitesOf } from './phase-graph.ts'
 
 /**
  * Lock-hash + lock-chain validation for recursive-mode runs.
@@ -110,13 +112,14 @@ export function isCoreArtifact(artifactFile: string): boolean {
  * Mirrors: [phase for phase in PHASE_SEQUENCE[:idx] if (run_dir / phase).exists()]
  */
 export function getPrerequisites(runDir: string, artifactFile: string): string[] {
-  const idx = phaseIndex(artifactFile)
-  if (idx <= 0) return []
-  const prereqs: string[] = []
-  for (const phase of PHASE_SEQUENCE.slice(0, idx)) {
-    if (existsSync(join(runDir, phase))) prereqs.push(phase)
-  }
-  return prereqs
+  // T17: delegated to the graph — the same query expressed as IN-EDGES. The first attempt FAILED the
+  // parity golden because the graph only had nodes for artifacts already on disk, while this function
+  // is asked about files that do not exist yet (checking prerequisites BEFORE creating one is the
+  // normal case). The graph now takes the queried artifact as an edge TARGET that emits no outgoing
+  // edge, which is exactly this function's semantics — and `lock.parity.spec.ts` is the proof.
+  const present = PHASE_SEQUENCE.filter((phase) => existsSync(join(runDir, phase)))
+  const graph = buildPhaseGraph({ sequence: PHASE_SEQUENCE, present, queried: [artifactFile] })
+  return prerequisitesOf(graph, artifactFile)
 }
 
 /**
@@ -249,15 +252,14 @@ export function getStaleDownstreamPhases(runDir: string, artifactFile: string):
 }
 
 export function getNextLegalPhase(runDir: string): string | null {
-  for (const phase of PHASE_SEQUENCE) {
-    const phasePath = join(runDir, phase)
-    const status = getLockStatus(phasePath)
-    if (status === 'LOCKED') continue
-    if (!existsSync(phasePath) && OPTIONAL_PHASES.has(phase)) continue
-    if (getPrerequisiteBlockers(runDir, phase).length > 0) return null
-    return phase
-  }
-  return null
+  // T17: delegated to the graph, which now models all three shipped rules (skip LOCKED; skip an
+  // ABSENT OPTIONAL phase; report BLOCKED rather than moving past a blocked node). `queried` carries
+  // the WHOLE sequence because an absent, required phase is a legitimate answer here, and the parity
+  // specs are the proof — the same goldens that caught the previous attempt.
+  const present = PHASE_SEQUENCE.filter((phase) => existsSync(join(runDir, phase)))
+  const locked = present.filter((phase) => getLockStatus(join(runDir, phase)) === 'LOCKED')
+  const graph = buildPhaseGraph({ sequence: PHASE_SEQUENCE, present, locked, queried: PHASE_SEQUENCE })
+  return nextLegalPhase(graph, { optional: OPTIONAL_PHASES })
 }
 
 /** All receipts whose prerequisite_hashes reference a missing or changed artifact. */
@@ -310,6 +312,141 @@ export function validateChain(runDir: string, runId: string): LockChainResult {
   return { runId, phases, breakPhase, nextLegalPhase, complete, staleReceipts }
 }
 
+/** Why a receipt chain failed verification. */
+export type ReceiptChainBreakKind =
+  | 'receipt-hash-mismatch'
+  | 'prerequisite-hash-mismatch'
+  | 'missing-prerequisite-receipt'
+  | 'malformed-previous-hash'
+
+/** One broken link, naming the phase at fault and both values involved. */
+export interface ReceiptChainBreak {
+  /** The artifact whose receipt is at fault. */
+  phase: string
+  kind: ReceiptChainBreakKind
+  /** A sentence naming both values, so the break is diagnosable without a debugger. */
+  detail: string
+}
+
+export interface ReceiptChainResult {
+  runId: string
+  ok: boolean
+  /** How many receipts were examined (absent phases are skipped, not counted). */
+  checked: number
+  breaks: ReceiptChainBreak[]
+}
+
+const RECEIPT_HASH_RE = /^[a-fA-F0-9]{64}$/
+
+/**
+ * T32 — verify a run's receipts against each other and against the artifacts they
+ * cite. Closes review finding E: the receipt hash was COMPUTED on every lock and
+ * never re-derived, so `previous_receipt_hash` was written and read by nothing.
+ *
+ * READ-ONLY, deliberately. The chain is evidence, and a verification that rewrites
+ * what it verifies is worthless — so this never repairs, re-hashes or touches a
+ * receipt, and a caller can run it as often as it likes.
+ *
+ * WHAT IT CHECKS, and what it refuses to claim. `previous_receipt_hash` chains to the
+ * SAME artifact's previous receipt, and there is exactly one receipt file per
+ * artifact, so the receipt it names has been overwritten and its LINKAGE cannot be
+ * verified from disk. Rather than assert a linkage it cannot prove, this checks:
+ *   1. receipt integrity — the stored `receipt_hash` must equal the hash recomputed
+ *      from the receipt's own fields (catches an edit after the fact);
+ *   2. prerequisite agreement — each recorded `prerequisite_hashes[p]` must equal
+ *      p's CURRENT artifact hash (catches an upstream changed after locking);
+ *   3. gaps — a receipt citing a prerequisite that has no receipt at all;
+ *   4. a well-formedness check on `previous_receipt_hash`, which the writer could
+ *      only ever produce as a sha256 hex digest or null.
+ *
+ * Never throws: an unreadable receipt is skipped, and a missing run directory is an
+ * empty result rather than an error.
+ */
+export function validateReceiptChain(runDir: string, runId: string): ReceiptChainResult {
+  const breaks: ReceiptChainBreak[] = []
+  let checked = 0
+
+  for (const phase of PHASE_SEQUENCE) {
+    const receipt = readReceipt(runDir, phase)
+    if (receipt === null) continue
+    checked += 1
+
+    // 1. INTEGRITY. Recompute the hash from every field the writer covered.
+    const { receipt_hash: storedHash, ...base } = receipt
+    const expectedHash = createHash('sha256').update(pythonJsonDumps(base), 'utf8').digest('hex')
+    if (storedHash !== expectedHash) {
+      // Two hashes alone say "something changed" but not WHAT, so the detail also
+      // compares the receipt's recorded artifact hash against the artifact on disk.
+      // That single comparison separates the two causes a reader cares about: the
+      // ARTIFACT was edited after locking, or the RECEIPT was edited after writing.
+      let onDisk: string | null = null
+      try {
+        onDisk = lockHashFromContent(readFileSync(join(runDir, phase), 'utf8'))
+      } catch {
+        onDisk = null
+      }
+      const recorded = String(receipt.artifact_hash)
+      const which = onDisk === null
+        ? 'the artifact cannot be read now'
+        : onDisk === recorded
+          ? 'the artifact still matches its recorded hash ' + recorded + ', so the RECEIPT was edited'
+          : 'the artifact now hashes ' + onDisk + ' but the receipt records ' + recorded + ', so the ARTIFACT changed after locking'
+      breaks.push({
+        phase,
+        kind: 'receipt-hash-mismatch',
+        detail: 'receipt_hash ' + String(storedHash) + ' does not match the recomputed ' + expectedHash + '; ' + which,
+      })
+    }
+
+    // 4. WELL-FORMEDNESS first among the cheap checks, and NOT skipped when the
+    // integrity check already failed: a tampered field is exactly when a malformed
+    // one is worth naming too.
+    const previous = receipt.previous_receipt_hash
+    if (previous !== null && previous !== undefined && !RECEIPT_HASH_RE.test(String(previous))) {
+      breaks.push({
+        phase,
+        kind: 'malformed-previous-hash',
+        detail: 'previous_receipt_hash ' + JSON.stringify(previous) + ' is not a sha256 hex digest or null',
+      })
+    }
+
+    // 2 + 3. The cited prerequisites must still agree with what is on disk.
+    const cited = receipt.prerequisite_hashes ?? {}
+    for (const prereq of Object.keys(cited)) {
+      const recorded = cited[prereq]
+      if (readReceipt(runDir, prereq) === null) {
+        breaks.push({
+          phase,
+          kind: 'missing-prerequisite-receipt',
+          detail: 'cites ' + prereq + ' as a locked prerequisite, but no receipt exists for it',
+        })
+        continue
+      }
+      let currentHash: string | null = null
+      try {
+        currentHash = lockHashFromContent(readFileSync(join(runDir, prereq), 'utf8'))
+      } catch {
+        currentHash = null
+      }
+      if (currentHash === null) {
+        breaks.push({
+          phase,
+          kind: 'prerequisite-hash-mismatch',
+          detail: 'cites ' + prereq + ' at ' + String(recorded) + ', but its artifact cannot be read now',
+        })
+      } else if (currentHash !== recorded) {
+        breaks.push({
+          phase,
+          kind: 'prerequisite-hash-mismatch',
+          detail: 'recorded ' + String(recorded) + ' for ' + prereq + ', which now hashes ' + currentHash,
+        })
+      }
+    }
+  }
+
+  return { runId, ok: breaks.length === 0, checked, breaks }
+}
+
 /**
  * Python json.dumps(obj, sort_keys=True, separators=(', ', ': '), ensure_ascii=True)
  * compact serialization. Exported for parity testing against the Python oracle.

package/src/memory-feedback.ts

@@ -0,0 +1,185 @@
+/**
+ * Memory feedback (FU-13 P3) — which entries were injected into which run, and how that run turned out.
+ *
+ * ⚠ WHAT THIS IS, HONESTLY LABELLED: a COUNTER, not learning. `TRAINING.md` puts model training (the
+ * reference's 58 KB GRPO script) out of scope for a workflow plugin. What is in scope is the loop that makes
+ * retrieval improve with evidence: record what was injected, settle it against the run's outcome, and let the
+ * selector prefer what has held up.
+ *
+ * ⚠ AND WHY THE COUNTERS LIVE IN A SIDECAR, NOT IN THE SHARDS. The memory plane's documents are
+ * human-authored: a person writes the lesson. Rewriting one to bump a number would be the silent-overwrite
+ * defect this repo already produced once (the closeout writing over phase documents), applied to the memory
+ * plane. So the counters live in `.recursive/memory/.feedback.json`, which is machine-owned and disposable —
+ * delete it and you lose ranking evidence, not knowledge.
+ *
+ * ⚠ NO TIMESTAMPS ANYWHERE: two runs with the same inputs must produce identical files, which is the same
+ * discipline the lock receipts, the closeout receipts and the selection output all follow.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
+export const FEEDBACK_FILE = 'memory/.feedback.json'
+
+/** Where a run records what it was shown. */
+export const INJECTIONS_FILE = 'memory-injections.json'
+
+/** One entry the agent was shown, as the run recorded it. */
+export interface InjectionRecord {
+  /** The entry's source path, which is also its identity in the counters. */
+  source: string
+  title: string
+  /** The phase it was injected for. */
+  phase: string
+  score: number
+}
+
+export interface FeedbackCounter {
+  /** Times an entry was injected for a phase that then locked on that round. */
+  applied: number
+  /** Times an entry was injected for a phase that had to come round again before it locked. */
+  contradicted: number
+}
+
+export type FeedbackBook = Record<string, FeedbackCounter>
+
+/** Read the counters. A missing or unreadable file is an empty book, never an error. */
+export function readFeedback(root: string, readFile: (path: string) => string | null = defaultRead): FeedbackBook {
+  const text = readFile(join(root, FEEDBACK_FILE))
+  if (text === null || text.trim() === '') return {}
+  try {
+    const parsed = JSON.parse(text) as unknown
+    if (typeof parsed !== 'object' || parsed === null) return {}
+    const book: FeedbackBook = {}
+    for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+      const record = value as Partial<FeedbackCounter> | null
+      if (record === null || typeof record !== 'object') continue
+      book[key] = {
+        applied: Number.isFinite(record.applied) ? Number(record.applied) : 0,
+        contradicted: Number.isFinite(record.contradicted) ? Number(record.contradicted) : 0,
+      }
+    }
+    return book
+  } catch {
+    return {}
+  }
+}
+
+/** Read what a run recorded being shown. */
+export function readInjections(runDir: string, readFile: (path: string) => string | null = defaultRead): InjectionRecord[] {
+  const text = readFile(join(runDir, INJECTIONS_FILE))
+  if (text === null || text.trim() === '') return []
+  try {
+    const parsed = JSON.parse(text) as unknown
+    return Array.isArray(parsed) ? parsed as InjectionRecord[] : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Record what the run was shown, MERGED by (source, title, phase).
+ *
+ * ⚠ MERGED RATHER THAN APPENDED, because a phase can be re-entered while it is still DRAFT and the same
+ * entries are selected again. Appending would count one decision as four, and the counters exist to be
+ * evidence. The highest score seen wins, since that is what the agent was most recently shown.
+ */
+export function recordInjection(
+  runDir: string,
+  entries: readonly { source: string; title: string; score: number }[],
+  phase: string,
+  write: (path: string, content: string) => void = defaultWrite,
+  readFile: (path: string) => string | null = defaultRead,
+): InjectionRecord[] {
+  const existing = readInjections(runDir, readFile)
+  const byKey = new Map<string, InjectionRecord>()
+  for (const record of existing) byKey.set(keyOf(record), record)
+  for (const entry of entries) {
+    const candidate: InjectionRecord = { source: entry.source, title: entry.title, phase, score: entry.score }
+    const key = keyOf(candidate)
+    const prior = byKey.get(key)
+    byKey.set(key, prior === undefined || candidate.score > prior.score ? candidate : prior)
+  }
+  // Deterministic order, so the file is comparable between runs.
+  const merged = [...byKey.values()].sort((a, b) => a.phase.localeCompare(b.phase)
+    || a.source.localeCompare(b.source) || a.title.localeCompare(b.title))
+  write(join(runDir, INJECTIONS_FILE), JSON.stringify(merged, null, 2) + '\n')
+  return merged
+}
+
+/**
+ * Settle a finished run against its own outcome and return the updated book.
+ *
+ * ⚠ THE OUTCOME SIGNAL, and it is deliberately modest: an entry injected for a phase that **locked** was
+ * APPLIED; an entry injected for a phase that had to come round again before it locked is CONTRADICTED — the
+ * memory did not carry the phase the first time. That is a real signal available from the run's own files,
+ * and it is not dressed up as more than that: no model was trained, and an entry is never deleted for losing.
+ */
+export function settleInjections(
+  root: string,
+  runDir: string,
+  lockedPhases: readonly string[],
+  write: (path: string, content: string) => void = defaultWrite,
+  readFile: (path: string) => string | null = defaultRead,
+): FeedbackBook {
+  const injections = readInjections(runDir, readFile)
+  const book = readFeedback(root, readFile)
+  const locked = new Set(lockedPhases)
+
+  // ⚠ ONLY `applied` IS SETTLED HERE, and the first version of this claimed more than it could show. It tried
+  // to count a CONTRADICTION when "the phase needed more than one round", but `recordInjection` MERGES by
+  // (source, title, phase) precisely so a re-entered DRAFT phase counts once — so the re-entry history that
+  // rule needs is discarded before settle ever sees it, and the counts came out wrong in a way a reader would
+  // have believed. `contradicted` stays in the type and in `feedbackBonus`, because the ranking already knows
+  // what to do with it; what is missing is an honest SOURCE for it (a re-opened phase), and until there is
+  // one, this function reports only what it can prove.
+  for (const record of injections) {
+    if (!locked.has(record.phase)) continue
+    const counter = book[record.source] ?? { applied: 0, contradicted: 0 }
+    counter.applied += 1
+    book[record.source] = counter
+  }
+
+  write(join(root, FEEDBACK_FILE), JSON.stringify(sortBook(book), null, 2) + '\n')
+  return book
+}
+
+/**
+ * What the counters are worth in the ranking: `applied - contradicted`, clamped to one step.
+ *
+ * Clamped because a single long-lived entry should not be able to dominate the ranking forever, and because
+ * the counter is evidence about retrieval, not a verdict about the lesson.
+ */
+export function feedbackBonus(book: FeedbackBook, source: string): number {
+  const counter = book[source]
+  if (counter === undefined) return 0
+  const net = counter.applied - counter.contradicted
+  return net === 0 ? 0 : net > 0 ? 1 : -1
+}
+
+function countPhase(injections: readonly InjectionRecord[], phase: string): number {
+  return injections.filter((record) => record.phase === phase).length
+}
+
+function keyOf(record: { source: string; title: string; phase: string }): string {
+  return record.phase + '\u0000' + record.source + '\u0000' + record.title
+}
+
+function sortBook(book: FeedbackBook): FeedbackBook {
+  const sorted: FeedbackBook = {}
+  for (const key of Object.keys(book).sort()) sorted[key] = book[key]
+  return sorted
+}
+
+function defaultRead(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function defaultWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, content, 'utf8')
+}