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

package/src/settlement.ts

@@ -0,0 +1,355 @@
+/**
+ * T36 — observe a delegated child's settlement WITHOUT reading session history.
+ *
+ * THE CONSTRAINT, VERIFIED IN THE CHECKOUT RATHER THAN ASSUMED. DSH prohibits new
+ * production calls to `Session.snapshotEvents()`, `Session.eventAt()` and
+ * `Session.ownEvents()`: *"existing logic may remain unmigrated for now, but new
+ * calls are prohibited"*, the rule is enforced by an executable lint check, and
+ * *"copying a waiver to a new production call violates this policy"*. The obvious
+ * implementation of an observer — scan the parent's log for the `subagent-settled`
+ * notice — is therefore exactly the thing that is forbidden, and it would also be
+ * the wrong shape: history reads make ordinary logic depend on storage.
+ *
+ * THE PRESCRIBED REPLACEMENT is to *"process the delivered current event"* or read
+ * maintained projection state. So this module never looks back. It recognises the
+ * settlement **at delivery time** (the `session/event` listener passes it as it is
+ * committed) and records it in the run's own file state, which is precisely the
+ * plugin's zero-emission, file-derived architecture: nothing is appended to the
+ * session, and the durable fact lands where every other plugin fact lands.
+ *
+ * WHY THE NOTICE ARRIVES AT ALL. A continuable child that finishes produces a
+ * durable user message in the parent whose source is `{ kind: 'subagent-settled' }`
+ * — the parent-side settlement seam. There is no promise to await, which is why
+ * `delegateContinuable` takes an injected observer instead of awaiting one.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { SubagentResultLike, ContinuableChildId, ContinuableMessageId } from './delegation.ts'
+
+/** A settlement notice, as the plugin records it. */
+export interface SettlementNotice {
+  /** The durable child this settles. */
+  childId: string
+  /** One line saying the child is finished and why, in the parent's vocabulary. */
+  summary: string
+  /** The child's own closing text, if it left any. */
+  closingText: string
+  /** The message id the notice arrived as, when the event carried one. */
+  messageId?: string
+}
+
+/** Minimal structural view of a delivered session event (no harness import). */
+export interface SessionEventLike {
+  type?: string
+  data?: unknown
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : null
+}
+
+function textOf(block: unknown): string {
+  const record = asRecord(block)
+  return record !== null && record.type === 'text' && typeof record.text === 'string' ? record.text : ''
+}
+
+/**
+ * Recognise a settlement notice from a DELIVERED session event, or null when the
+ * event is not one. Pure: no I/O, no history read, safe on any event.
+ *
+ * The notice's shape is the harness's: a `user/message` whose `source.kind` is
+ * `subagent-settled` and whose `source.senderSessionId` names the child. The
+ * content is a summary line, then optionally `Its closing message:` followed by
+ * the child's own text — so the closing text is everything after that marker, and
+ * a child that left nothing yields the harness's own "It left no closing message."
+ */
+export function settlementFromEvent(event: SessionEventLike): SettlementNotice | null {
+  if (event?.type !== 'user/message') return null
+  const message = asRecord(event.data)
+  if (message === null) return null
+  const source = asRecord(message.source)
+  if (source === null || source.kind !== 'subagent-settled') return null
+  const childId = typeof source.senderSessionId === 'string' ? source.senderSessionId : ''
+  if (childId === '') return null
+
+  const content = Array.isArray(message.content) ? message.content : []
+  const texts = content.map(textOf).filter((t) => t !== '')
+  const markerIndex = texts.findIndex((t) => t === 'Its closing message:')
+  const summary = typeof source.summary === 'string' && source.summary !== ''
+    ? source.summary
+    : (texts[0] ?? '')
+  const closingText = markerIndex >= 0 ? texts.slice(markerIndex + 1).join('\n\n') : ''
+
+  const notice: SettlementNotice = { childId, summary, closingText }
+  if (typeof message.id === 'string' && message.id !== '') notice.messageId = message.id
+  return notice
+}
+
+/** The run-scoped append-only settlement log. */
+export function settlementLogPath(runDir: string): string {
+  return join(runDir, 'subagents', 'settlements.jsonl')
+}
+
+/**
+ * Which run owns this child, resolved from the FILESYSTEM alone.
+ *
+ * The delivered event names the child (`source.senderSessionId`) but not the run,
+ * and the plugin's whole design is to derive placement from what is on disk rather
+ * than to keep a registry that could go stale. A delegation writes its child
+ * directories as `subagents/<delegationId>/child-<childId>/`, so the run holding
+ * that child is the run the settlement belongs to.
+ *
+ * AMBIGUITY RETURNS NULL rather than guessing. Two runs claiming the same child
+ * would mean a copied tree, and filing a settlement into the wrong run is worse
+ * than not filing it: it would attach one run's evidence to another run's chain.
+ * A miss costs a settlement the loop will report as "no settlement yet", which is
+ * recoverable; mis-filing is not.
+ */
+export function runDirForChild(root: string, childId: string): string | null {  if (childId === '' || root === '') return null
+  const runsRoot = join(root, '.recursive', 'run')
+  let runs: string[]
+  try {
+    runs = readdirSync(runsRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort()
+  } catch {
+    return null
+  }
+
+  const matches: string[] = []
+  for (const runName of runs) {
+    const runDir = join(runsRoot, runName)
+    let delegations: string[]
+    try {
+      delegations = readdirSync(join(runDir, 'subagents'), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+    } catch {
+      continue
+    }
+    for (const delegationId of delegations) {
+      if (existsSync(join(runDir, 'subagents', delegationId, 'child-' + childId))) {
+        matches.push(runDir)
+        break
+      }
+    }
+  }
+  return matches.length === 1 ? matches[0]! : null
+}
+
+/**
+ * Record one notice in the run's file state. APPEND-ONLY, matching the run's own
+ * evidence posture: a settlement that already happened is a fact, and rewriting
+ * the log would let a later write erase the record of an earlier round.
+ */
+export function recordSettlement(runDir: string, notice: SettlementNotice): string {
+  const path = settlementLogPath(runDir)
+  mkdirSync(dirname(path), { recursive: true })
+  appendFileSync(path, JSON.stringify(notice) + '\n', 'utf8')
+  return path
+}
+
+/** Every recorded notice for a run, in arrival order. Never throws. */
+/**
+ * ⚠ FU-17 — THE ADOPTION PATH, for a settlement whose child this plugin never filed.
+ *
+ * WHY IT EXISTS. `runDirForChild` attributes a child by the `subagents/<delegation>/child-<id>/` layout that a
+ * delegation writes, and it refuses to guess — its own comment: *"filing a settlement into the wrong run is worse
+ * than not filing it: it would attach one run's evidence to another run's chain. A miss costs a settlement the
+ * loop will report as 'no settlement yet', which is recoverable; mis-filing is not."*
+ *
+ * That refusal is right, and it has a cost this feature cannot accept: a child started through the harness's own
+ * tools (or any path that did not write a delegation directory) settles into nothing, so the run loses evidence
+ * of work that really happened — and a phase artifact that must cite an action record cannot cite one that was
+ * never filed.
+ *
+ * THE RULE IS PROGRESSIVE AND NEVER GUESSES BETWEEN RUNS:
+ *   1. exactly one run under the root  → file into THAT run, under a clearly-marked `adopted-<child>/` directory,
+ *      and say in the record that it was adopted and why;
+ *   2. more than one run               → file into a ROOT-level `adopted-settlements.jsonl` instead, because
+ *      choosing between runs is exactly the mis-filing the rule above forbids. The fact is still recorded, in a
+ *      place that can attribute nothing to the wrong chain.
+ *
+ * Returns the path it wrote, or null when there was nothing to write. Never throws: this rides the same hot path
+ * as `captureSettlement` and must not break the session it observes.
+ */
+export function adoptSettlement(root: string, notice: SettlementNotice): string | null {
+  if (notice.childId === '') return null
+  try {
+    const runsRoot = join(root, '.recursive', 'run')
+    let runs: string[] = []
+    try {
+      runs = readdirSync(runsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+    } catch {
+      return null
+    }
+
+    // Case 2 — ambiguous, so it is recorded OUTSIDE every run's evidence chain.
+    if (runs.length !== 1) {
+      const path = join(root, '.recursive', 'adopted-settlements.jsonl')
+      mkdirSync(dirname(path), { recursive: true })
+      appendFileSync(path, JSON.stringify({
+        adopted: true,
+        reason: 'no delegation directory for this child, and ' + runs.length + ' runs exist',
+        run: null,
+        childId: notice.childId,
+        summary: notice.summary,
+        closingText: notice.closingText,
+      }) + '\n', 'utf8')
+      return path
+    }
+
+    // Case 1 — one run, so the child can only belong to it. Still marked as adopted: the delegation directory
+    // the normal path would have used does not exist, and a reader must be able to tell the two apart.
+    const path = join(runsRoot, runs[0]!, 'subagents', 'adopted-' + notice.childId, 'settlement.jsonl')
+    mkdirSync(dirname(path), { recursive: true })
+    appendFileSync(path, JSON.stringify({
+      adopted: true,
+      reason: 'no delegation directory for this child; single-run workspace',
+      childId: notice.childId,
+      summary: notice.summary,
+      closingText: notice.closingText,
+    }) + '\n', 'utf8')
+    return path
+  } catch {
+    return null
+  }
+}
+
+export function readSettlements(runDir: string): SettlementNotice[] {  let raw: string
+  try {
+    raw = readFileSync(settlementLogPath(runDir), 'utf8')
+  } catch {
+    return []
+  }
+  const out: SettlementNotice[] = []
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    try {
+      const parsed = asRecord(JSON.parse(trimmed))
+      if (parsed !== null && typeof parsed.childId === 'string' && typeof parsed.summary === 'string') {
+        const notice: SettlementNotice = {
+          childId: parsed.childId,
+          summary: parsed.summary,
+          closingText: typeof parsed.closingText === 'string' ? parsed.closingText : '',
+        }
+        if (typeof parsed.messageId === 'string') notice.messageId = parsed.messageId
+        out.push(notice)
+      }
+    } catch {
+      // A malformed line is skipped rather than failing the whole read: a log
+      // that a partial write corrupted must not make the run unobservable.
+    }
+  }
+  return out
+}
+
+/** The LATEST recorded settlement for one child, or null when none has landed. */
+export function readSettlement(runDir: string, childId: string): SettlementNotice | null {
+  const mine = readSettlements(runDir).filter((n) => n.childId === childId)
+  return mine.length === 0 ? null : mine[mine.length - 1]!
+}
+
+/**
+ * Turn a recorded settlement into the result shape the delegation loop reads.
+ *
+ * `success` is deliberately NOT asserted from the summary: the notice reports how
+ * the child's turn ENDED, not whether its work is acceptable. Acceptance is the
+ * verdict's job (`readVerdict` + `evaluateDelegationResult`), and defaulting to
+ * success here would let a stopped child be treated as a passing review — the
+ * exact silent-approval failure `delegateContinuable` refuses to fabricate.
+ */
+export function settlementResult(notice: SettlementNotice): SubagentResultLike {
+  const result: SubagentResultLike = {
+    output: notice.closingText,
+    stopReason: 'completed',
+  } as SubagentResultLike
+  // A child that reported structured JSON leaves it as the closing text.
+  const parsed = (() => {
+    try { return JSON.parse(notice.closingText) } catch { return undefined }
+  })()
+  if (parsed !== undefined) (result as { structured?: unknown }).structured = parsed
+  return result
+}
+
+/**
+ * Build the `awaitRoundResult` observer the continuable loop injects.
+ *
+ * ⚠ IT NOW WAITS, AND THAT IS THE FU-9 DECISION (option a, chosen by the user). It used to read the
+ * settlement log ONCE and return null immediately, which the loop reports as `parked` — a correct signal, but
+ * it meant the parent returned before the child had run at all. The control that shows why that matters: the
+ * harness's own team fixture, same recipe, completed two teammates while this plugin's delegated child never
+ * got a turn — and the engine's contract explains it, `submitAdmitted` *"crosses the final admission cutoff
+ * and submits without yielding"*, so a parent that returns lets the host go idle, and an idle one-shot session
+ * never pumps the child's inbox.
+ *
+ * ⚠ THE PARK IS KEPT, as the fallback it always was. The wait is bounded by `timeoutMs`; when the deadline
+ * passes the observer STILL returns null, so the caller still parks, still resumes on a later turn with the
+ * SAME child id, and still never treats an unobserved round as approval — the T36 rules are intact. What
+ * changed is that parking is now what happens AFTER a real wait rather than INSTEAD of one.
+ *
+ * `sleep` is injectable so a test asserts the waiting without spending wall-clock time, and `timeoutMs: 0`
+ * reproduces the old read-once behaviour exactly — which is what the tests that assert a park use.
+ */
+export function settlementRoundObserver(
+  runDir: string,
+  options: { timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void> } = {},
+): (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null> {
+  const timeoutMs = options.timeoutMs ?? 30_000
+  const pollMs = options.pollMs ?? 250
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  return async (childId: ContinuableChildId) => {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const notice = readSettlement(runDir, String(childId))
+      if (notice !== null) return settlementResult(notice)
+      if (Date.now() >= deadline) return null
+      await sleep(pollMs)
+    }
+  }
+}
+
+/**
+ * Handle one delivered session event: record it when it is a settlement, and
+ * report whether it was one. Wired to `ctx.on('session/event', …)`, which the
+ * harness documents as the delivery point for every committed event.
+ */
+export function captureSettlement(runDir: string, event: SessionEventLike): SettlementNotice | null {
+  const notice = settlementFromEvent(event)
+  if (notice === null) return null
+  recordSettlement(runDir, notice)
+  return notice
+}
+
+/**
+ * FU-3 — the children a run has on its books, read from the layout the delegations already write.
+ *
+ * WHY FROM DISK AND NOT FROM MEMORY. A delegation records itself as `subagents/<delegationId>/child-<childId>/`
+ * (see {@link runDirForChild}), which is the same fact the settlement log is keyed on. Reading it back
+ * means a drain at closeout works **in a fresh process** — after a resume, a crash or a compaction — where
+ * an in-memory list of children would be empty and the run would silently leak every child it started.
+ *
+ * ⚠ AN EMPTY ANSWER IS A REAL ANSWER: a run that delegated nothing has no children, and the caller must
+ * be able to tell that from a failed lookup — hence a plain `[]` rather than `null`.
+ */
+export function runChildIds(runDir: string): string[] {
+  const base = join(runDir, 'subagents')
+  if (!existsSync(base)) return []
+  const ids: string[] = []
+  for (const delegation of readdirSync(base, { withFileTypes: true })) {
+    if (!delegation.isDirectory()) continue
+    const delegationDir = join(base, delegation.name)
+    for (const child of readdirSync(delegationDir, { withFileTypes: true })) {
+      if (child.isDirectory() && child.name.startsWith('child-')) {
+        const id = child.name.slice('child-'.length)
+        if (id !== '' && !ids.includes(id)) ids.push(id)
+      }
+    }
+  }
+  return ids
+}

package/src/skills-phase.ts

@@ -0,0 +1,143 @@
+/**
+ * T12 — register each phase's rules as a SKILL, so they are discoverable in the catalogue.
+ *
+ * WHY. Phase 8 writes skill memory to the filesystem, and a phase's rules otherwise live only in
+ * this plugin's `phase-rules.ts` — reachable by grepping a checkout, not by the agent or a child
+ * asking what a phase requires. The native `ctx.skills` registry is a *catalogue*: a skill it
+ * holds is discoverable by name, addressable by `get()`, and visible to a discovery consumer.
+ * Registering the phase rules there is what turns "the rules are in the source" into "the rules
+ * are answerable".
+ *
+ * ⚠ THE REGISTRATION IS A RUNTIME CONTRIBUTION, and the harness names that source explicitly
+ * (`SkillSource` includes `'runtime'`). Declaring `source: 'runtime'` is not decoration: it is how
+ * the registry can tell this skill apart from one a checkout or a user directory supplied, and it
+ * is what makes the plugin's contribution replaceable rather than tangled with the filesystem's.
+ *
+ * ⚠ AN ABSENT REGISTRY IS NOT A FAILURE. `ctx.skills` is an optional service; with none mounted
+ * the helper does nothing and SAYS it did nothing (`skipped: true`) — the plugin's convention for
+ * every optional seam, because a composition without a catalogue should still run the workflow.
+ */
+import { phaseRulesFor, type PhaseRules } from './phase-rules.ts'
+
+/** The prefix every phase skill carries, so the plugin's contributions are recognisable. */
+export const PHASE_SKILL_PREFIX = 'recursive-phase'
+
+/**
+ * One runtime skill contribution.
+ *
+ * Structural rather than imported from the harness: the plugin models every harness touchpoint as
+ * a minimal seam, and this keeps the shape testable with a fake registry.
+ */
+export interface PhaseSkillRegistration {
+  name: string
+  description: string
+  whenToUse?: string
+  content: string
+  /** A RUNTIME contribution — see the module comment for why this is declared, not implied. */
+  source: 'runtime'
+}
+
+export interface SkillRegistryLike {
+  register(registration: PhaseSkillRegistration): () => void
+}
+
+/**
+ * The skill name for a phase file.
+ *
+ * Kebab-case, because the registry addresses skills by a kebab-case identifier — and STABLE,
+ * because a discoverable rule nobody can name is not discoverable. `01.5-root-cause.md` becomes
+ * `recursive-phase-01-5-root-cause`: the dot cannot survive, and dropping the sub-phase number
+ * would collide it with a whole phase.
+ */
+export function phaseSkillName(fileName: string): string {
+  const slug = fileName
+    .replace(/\.md$/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return PHASE_SKILL_PREFIX + '-' + slug
+}
+
+/** The markdown body a reader gets from the catalogue. */
+function phaseSkillContent(rules: PhaseRules): string {
+  const lines: string[] = []
+  lines.push('# Phase rules: ' + rules.fileName)
+  lines.push('')
+  lines.push('This phase is ' + rules.label + '. Its required sections are checked by the linter,')
+  lines.push('and a missing one is a lint failure — not a style preference.')
+  lines.push('')
+  lines.push('## Required sections')
+  lines.push('')
+  for (const section of rules.requiredSections) {
+    lines.push('- ' + section)
+  }
+  if (rules.requiredSections.length === 0) {
+    lines.push('- (none declared for this phase)')
+  }
+  lines.push('')
+  lines.push('## Flags')
+  lines.push('')
+  lines.push('- audited: ' + (rules.audited ? 'yes — this phase needs a delegated audit' : 'no'))
+  lines.push('- tdd: ' + (rules.tdd ? 'yes — the TDD Compliance gate applies' : 'no'))
+  lines.push('- qa: ' + (rules.qa ? 'yes — the manual QA gate applies' : 'no'))
+  return lines.join('\n')
+}
+
+/** Build the registration for one phase. Pure, so the mapping is testable without a registry. */
+export function phaseSkillRegistration(rules: PhaseRules): PhaseSkillRegistration {
+  const gates: string[] = []
+  if (rules.audited) gates.push('audited')
+  if (rules.tdd) gates.push('TDD')
+  if (rules.qa) gates.push('QA')
+  return {
+    name: phaseSkillName(rules.fileName),
+    description: 'Rules for ' + rules.fileName + ' (' + rules.label + '): its required sections and gates.',
+    whenToUse: 'Use when authoring, linting or reviewing ' + rules.fileName
+      + (gates.length === 0 ? '.' : ', which carries the ' + gates.join(' / ') + ' gate(s).'),
+    content: phaseSkillContent(rules),
+    source: 'runtime',
+  }
+}
+
+export interface PhaseSkillRegistrationResult {
+  /** Names registered, in phase order. */
+  registered: string[]
+  /** Disposers, so a caller can withdraw the contribution with its own effects. */
+  disposers: Array<() => void>
+  /** True when there was no registry: nothing was registered, and that is not an error. */
+  skipped: boolean
+}
+
+/**
+ * Register every phase's rules as a skill.
+ *
+ * Takes `fileNames` rather than reading a directory so the caller decides WHICH phases this
+ * composition exposes; the rules themselves come from `phaseRulesFor`, so there is one definition
+ * of what a phase requires and no second copy to drift.
+ */
+export function registerPhaseSkills(
+  skills: SkillRegistryLike | null | undefined,
+  fileNames: readonly string[],
+  workflowProfile?: string,
+): PhaseSkillRegistrationResult {
+  if (skills === null || skills === undefined || typeof skills.register !== 'function') {
+    return { registered: [], disposers: [], skipped: true }
+  }
+  const registered: string[] = []
+  const disposers: Array<() => void> = []
+  for (const fileName of fileNames) {
+    const registration = phaseSkillRegistration(phaseRulesFor(fileName, workflowProfile))
+    disposers.push(skills.register(registration))
+    registered.push(registration.name)
+  }
+  return { registered, disposers, skipped: false }
+}
+
+/**
+ * A board-facing line for the registration result — says SKIPPED out loud rather than leaving a
+ * reader to infer a missing catalogue from an empty list.
+ */
+export function describePhaseSkills(result: PhaseSkillRegistrationResult): string {
+  if (result.skipped) return 'phase rules were NOT registered as skills: no skill registry is mounted'
+  return result.registered.length + ' phase rule skill(s) registered: ' + result.registered.join(', ')
+}

package/src/snapshot.ts

@@ -12,9 +12,9 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { discoverRuns } from './run.ts'
-import { foldRun } from './status.ts'
+import { foldRun, pendingWork } from './status.ts'
 import { getLockStatus, receiptPath, readReceipt } from './lock.ts'
-import type { RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState } from './types.ts'
+import type { PhasePosition, RecursiveProjection, RecursiveRunCard, RecursivePhaseRow, RecursiveRunState, RecursiveTamper } from './types.ts'
 
 /** One locked-phase fact from a lock receipt (artifacts/<file>.receipt.json). */
 interface LockFacts {
@@ -41,8 +41,11 @@ function lockFactsOf(runDir: string, artifact: string): LockFacts {
 }
 
 /** One phase row from a run's folded status (locked facts enriched). */
-function phaseRowOf(runDir: string, key: string, file: string, status: string): RecursivePhaseRow {
+function phaseRowOf(runDir: string, key: string, file: string, status: string, position?: PhasePosition): RecursivePhaseRow {
   const row: RecursivePhaseRow = { phase: key, status }
+  // T21: carry the server's single derived position onto the wire so the board
+  // reads ONE value instead of recombining status/gates/lock fields itself.
+  if (position !== undefined) row.position = position
   if (status === 'LOCKED') {
     const facts = lockFactsOf(runDir, file)
     if (facts.lockedAt !== undefined) row.lockedAt = facts.lockedAt
@@ -63,7 +66,7 @@ export function foldRunCard(runDir: string, runId: string, worktreeRoot: string)
   // would never match the filename regex and would break columnForRun/cardFacts.
   const phases: Record<string, RecursivePhaseRow> = {}
   for (const phase of status.phases) {
-    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status)
+    if (phase.exists) phases[phase.file] = phaseRowOf(runDir, phase.file, phase.file, phase.status, phase.position)
   }
   const state = runStateOf(status)
   return {
@@ -71,17 +74,45 @@ export function foldRunCard(runDir: string, runId: string, worktreeRoot: string)
     worktreeRoot,
     phases,
     state,
-    tampers: {},
+    tampers: tampersOf(status),
     subagents: {},
+    // T18: the card carries the same DERIVED pending set the lock gate enforces,
+    // so the board explains a refusal instead of only recording it. Derived on
+    // every fold, so a cold resume shows it and no store is involved (§4.0).
+    pendingWork: pendingWork(runDir),
   }
 }
 
+/**
+ * T15 (F) — tamper facts by DERIVATION, never by persistence.
+ *
+ * `foldRun` already decides, per phase, whether a LOCKED artifact's stored hash
+ * still matches its content: a mismatch lands in `lockProblems` as the literal
+ * 'LockHash mismatch' and clears `lockValid`. That IS the tamper fact, so the
+ * card reads it off the fold instead of replaying the observed-tamper log —
+ * which means it survives a cold resume, honours plan §4.0 ("derived beats
+ * stored"), and stays correct even if the log was rotated or never written.
+ *
+ * Keyed by artifact FILE NAME (e.g. '00-requirements.md'), matching the phase
+ * keys above. `foldRun` itself is untouched: its output shape is
+ * parity-asserted by tests/status.parity.spec.ts.
+ */
+function tampersOf(status: ReturnType<typeof foldRun>): Record<string, RecursiveTamper> {
+  const tampers: Record<string, RecursiveTamper> = {}
+  for (const phase of status.phases) {
+    if (phase.status !== 'LOCKED' || phase.lockValid) continue
+    if (!phase.lockProblems.includes('LockHash mismatch')) continue
+    tampers[phase.file] = { path: phase.file, reason: phase.lockProblems.join('; ') }
+  }
+  return tampers
+}
+
 /**
  * Derive the run-level state from the folded status. The fs stores no run-level
  * state file, so the honest mapping is: 'complete' when every non-optional phase
- * exists and is lock-valid, else 'active'. Transient facts (gateBlocked, tamper,
- * subagent activity) are NOT fs-recoverable and read as absent (recorded
- * limitation; future enhancement).
+ * exists and is lock-valid, else 'active'. Tamper facts ARE fs-recoverable and
+ * are derived by tampersOf above; gateBlocked and subagent activity are not
+ * (recorded limitation; future enhancement).
  */
 function runStateOf(status: ReturnType<typeof foldRun>): RecursiveRunState {
   const mandatory = status.phases.filter(p => !p.optional)