@1aboveio/skills 0.10.0

package/skills/engineering/resolve-issues/scripts/postmortem.mjs

@@ -0,0 +1,909 @@
+// NOT A CLI. Running this file directly does nothing — no output, exit 0 — because it has no
+// entry point. `run-state.mjs postmortem <slug> [--json]` is the entry point,
+// and it does work this module cannot: it derives scheduler/manifest context this file never sees.
+//
+// A guard that says so out loud was tried and reverted. It has to import the shared main-module
+// helper from `engineering-runtime`, and `run-state.mjs` imports THIS file at load — so the new
+// edge changed which module a runtime-missing install reports first, turning an actionable "the
+// coherence contract is missing" into "a helper is missing". Degrading an operator-facing
+// fail-closed diagnostic to catch an authoring mistake is the wrong trade; the docs now link the
+// command text at `run-state.mjs`, and a test pins that they keep doing so.
+// The run's post-mortem: what the loop spent its wall-clock on, and what to change.
+//
+// MANDATORY and AUTOMATIC. It runs at the handoff whether or not anyone asks, and it
+// persists to disk without being asked, because the diagnostic value is CROSS-RUN: one
+// run's profile is an anecdote, and the question worth answering — is this loop getting
+// faster or slower, and at what — needs the last twenty. A pass that runs only when
+// someone already suspects a problem never runs on the runs that set the baseline.
+//
+// It is also the pass most likely to be skipped, for a reason worth naming: it fires at
+// the handoff, when the run is over and everyone involved believes they know how it went.
+// That belief is the thing it exists to contradict, so it does not ask permission.
+//
+// Why a renderer rather than a step that says "reflect on the run". The findings below
+// were all found by hand, once, on `epic-563-admin-transactions` (2026-08-07: 4 units,
+// 626 minutes, ~10.4 hours). Every one of them is a fact the manifest already held and
+// nobody read: three rounds bought after a PASS, a unit admitted at minute 347 of 626, a
+// cap of 2 on a four-unit roster, `pushedSha` unrecorded on every unit. A prose
+// instruction to "profile the run" degrades into a summary of what the orchestrator
+// remembers, which is the narration it already produced and already believes. Computing
+// them from state is the whole point: the post-mortem's job is to disagree with the
+// narration.
+//
+// The honesty rule is report.mjs's, unchanged: never invent what the manifest does not
+// hold. This module reads ONLY the run manifest — no transcripts, no harness paths, no
+// clock — so it runs identically in a consumer repo, in CI, and on a resumed run. That
+// bounds what it can see (it cannot time a spawn, so it cannot tell you a producer ran
+// slowly) and everything it does see is a fact with a timestamp behind it.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { DEFAULT_IN_FLIGHT_CAP, deriveComponents, isResolvedUnit, isDoneUnit } from './interference.mjs'
+import { deliveryForUnit, terminalDisposition } from './terminal-dispositions.mjs'
+import { roundsAfterPass } from './fix-rounds.mjs'
+
+const isObject = (v) => v != null && typeof v === 'object' && !Array.isArray(v)
+const arr = (v) => (Array.isArray(v) ? v.filter(isObject) : [])
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== ''
+
+// ---- where the profiles live ----
+//
+// Never the DEFAULT run dir, which is `$TMPDIR/resolver-runs` and gets cleared by the OS —
+// right for a manifest, whose job ends with its run, and fatal for a profile, whose entire
+// job is to still be there twenty runs later. Three levels, most specific first:
+//
+//   RESOLVER_POSTMORTEM_DIR   explicit, wins outright
+//   RESOLVER_RUN_DIR          a caller who set this CHOSE a location, so it is durable by
+//                             their decision — profiles go in a subdirectory of it. This
+//                             also scopes every test that already points the run dir at a
+//                             tmpdir, so a CLI test cannot write into the developer's home.
+//   (neither)                 XDG state — never tmp
+//
+// Slug sanitising is duplicated from run-state.mjs rather than imported: run-state.mjs
+// imports THIS module, and reaching back would make the cycle real. It is one regex, and
+// the alternative is an import cycle for a shared one-liner.
+export function postmortemDir(env = process.env) {
+  if (nonEmpty(env?.RESOLVER_POSTMORTEM_DIR)) return env.RESOLVER_POSTMORTEM_DIR.replace(/\/+$/, '')
+  if (nonEmpty(env?.RESOLVER_RUN_DIR)) return path.join(env.RESOLVER_RUN_DIR.replace(/\/+$/, ''), 'postmortems')
+  const state = nonEmpty(env?.XDG_STATE_HOME)
+    ? env.XDG_STATE_HOME.replace(/\/+$/, '')
+    : path.join(os.homedir(), '.local', 'state')
+  return path.join(state, 'resolver-postmortems')
+}
+
+const safeSlug = (slug) => String(slug ?? '').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'run'
+
+export function postmortemPaths(slug, env = process.env) {
+  const dir = postmortemDir(env)
+  const base = safeSlug(slug)
+  return {
+    dir,
+    json: path.join(dir, `${base}.json`),
+    text: path.join(dir, `${base}.txt`),
+    index: path.join(dir, 'index.jsonl'),
+  }
+}
+
+const ms = (a, b) => {
+  const x = Date.parse(a); const y = Date.parse(b)
+  return Number.isFinite(x) && Number.isFinite(y) ? y - x : null
+}
+const mins = (v) => (v == null ? null : Math.round(v / 60000))
+const fmt = (m) => (m == null ? '—' : m >= 60 ? `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m` : `${m}m`)
+
+// A unit's own timeline, to the extent the manifest recorded one. `rounds[].at` is
+// optional (validateRoundLog allows it absent), so every consumer below tolerates null
+// rather than treating a missing timestamp as zero — a run that did not stamp its rounds
+// gets fewer findings, not wrong ones.
+// Prefer, in order (#791 / issue-664 / identity#669):
+//   1. delivery.mergedAt — GitHub's merge time / verified-merge clock
+//   2. attempt.at when that attempt's outcome is `merged`
+//   3. null (no delivery clock)
+// A late record-delivery-* after the PR already merged must not inflate unitSpan.delivered
+// into a multi-hour co-delivery finding. `outcomeWritten` keeps the bookkeeping clock so
+// findOutcomeWriteLag can name the lag separately.
+export function unitSpan(unit, manifest = null) {
+  const delivery = deliveryForUnit(unit, manifest)
+  const rounds = arr(unit.rounds).filter((r) => nonEmpty(r.at))
+  const attempts = arr(delivery?.attempts).filter((a) => nonEmpty(a.at))
+  const firstRound = rounds[0]?.at ?? null
+  const lastRound = rounds.length ? rounds[rounds.length - 1].at : null
+  const firstPass = rounds.find((r) => r.verdict === 'PASS')?.at ?? null
+  const mergedAttemptAt = attempts.filter((a) => a.outcome === 'merged').slice(-1)[0]?.at
+    ?? (delivery?.outcome === 'merged' ? (attempts.slice(-1)[0]?.at ?? null) : null)
+  const mergedAt = nonEmpty(delivery?.mergedAt) ? delivery.mergedAt : null
+  const delivered = delivery?.outcome === 'merged'
+    ? (mergedAt ?? mergedAttemptAt)
+    : null
+  // Bookkeeping clock: when the terminal outcome / last attempt was written. Distinct from
+  // `delivered` so a late write after a real merge can be named without inventing wait.
+  const outcomeWritten = delivery?.outcome === 'merged'
+    ? (delivery.outcomeAt ?? attempts.slice(-1)[0]?.at ?? null)
+    : null
+  return { firstRound, lastRound, firstPass, delivered, outcomeWritten, mergedAt, roundCount: arr(unit.rounds).length }
+}
+
+// The run's wall-clock, from `createdAt` to the latest timestamp anything recorded —
+// including `updatedAt`, which is the only one that moves for work after the last round
+// (delivery watches, the handoff itself). Taking the max over rounds alone under-measures
+// every run that did anything after its final verdict, which is all of them.
+function runMinutes(m) {
+  if (!nonEmpty(m?.createdAt)) return null
+  const stamps = [m.updatedAt, ...arr(m.units).flatMap((u) => [
+    ...arr(u.rounds).map((r) => r.at),
+    ...arr(u.delivery?.attempts).map((a) => a.at),
+  ]), ...arr(m.components).flatMap((component) => [
+    ...arr(component.delivery?.attempts).map((attempt) => attempt.at),
+    ...arr(component.delivery?.observations).map((observation) => observation.at),
+    component.delivery?.mergedAt,
+    component.delivery?.outcomeAt,
+  ])].filter(nonEmpty).filter((s) => Number.isFinite(Date.parse(s)))
+  if (!stamps.length) return null
+  const end = stamps.reduce((latest, s) => (Date.parse(s) > Date.parse(latest) ? s : latest), stamps[0])
+  const d = mins(ms(m.createdAt, end))
+  return d != null && d > 0 ? d : null
+}
+
+// ---- the findings ----
+//
+// Each is { id, severity, headline, detail, evidence[], recommendation }. Ranked by
+// measured cost where the manifest supports a number and by severity where it does not —
+// an unranked list of six equal-looking findings is a list nobody acts on.
+
+// Buckets a reported round's cost on `round.headMoved` — the label #760's classification
+// already produces, READ here, never re-derived from headSha. `true` (demoted/probable
+// rebase) rounds get their own subtotal (`demotedCostMinutes`), reported but never fed
+// into `costMinutes` — the field `profile()`'s ranking comparator reads — because a
+// demoted round's gap is dominated by queue wait (a rebase's overnight wait, not review
+// time) and blending it into the ranked figure would reintroduce the same order of
+// inflation #761 exists to kill, one seam downstream of where it was found. Anything else
+// (`false`/unowed, `null`/unadjudicated) is the finding's actual claim.
+//
+// This is still elapsed time, not review time, in EITHER bucket — the gap before a round
+// includes queue wait as well as the round itself. That is fully owed for a demoted round
+// (a real rebase's wait was never unowed) and is exactly why its cost stays out of the
+// ranked figure; for an unowed round it is defensible only because the round itself
+// should not have existed, so none of the elapsed time before it was owed either.
+//
+// A round whose gap cannot be computed drops OUT of its bucket's sum rather than folding in
+// as a silent zero (AC3) — each bucket tracks its own `*Unknown` count, so "this round
+// genuinely cost nothing" and "this round's cost could not be computed" never collapse into
+// the same reported number, in either bucket.
+//
+// TWO things make a gap uncomputable, and they have to be treated alike (#771). The obvious
+// one is a missing `at`/`priorAt`. The other is a NEGATIVE gap — the round's own timestamp
+// earlier than the round before it — which is reachable without any bug here:
+// `validateRoundLog` never ties round order to time order, so an out-of-order log is valid;
+// `roundsAfterPass` walks array order without sorting; and this reads a SAVED manifest that
+// nothing re-validates. Clock skew across hosts, a hand-edited manifest, or timestamps
+// written out of order during recovery all produce it. Clamping such a gap to zero would
+// charge nothing AND count the round as successfully priced — arriving at the same silent
+// zero AC3 exists to forbid, by a second route and with nothing tracking it. So a negative
+// gap is unpriceable, exactly like a missing one.
+//
+// The sign check has to run on the RAW millisecond gap, before `mins()` rounds it (#771
+// reopened): `mins()` is `Math.round(v / 60000)`, and `Math.round(-0.5) === -0` in JS, so a
+// backwards gap in [-30s, 0) — clock skew's common magnitude, not the rare large inversion —
+// rounds to `-0`, and `-0 >= 0` is `true`. Guarding the rounded value let exactly that range
+// through, byte-identical to the `Math.max(d, 0)` clamp this fix exists to remove.
+export function bucketRoundCost(hits) {
+  let cost = 0
+  let costUnknown = 0
+  let demotedCost = 0
+  let demotedUnknown = 0
+  let demotedCount = 0
+  for (const { round } of arr(hits)) {
+    const gapMs = nonEmpty(round.at) && nonEmpty(round.priorAt) ? ms(round.priorAt, round.at) : null
+    // `>= 0` rather than `Math.max(d, 0)`: a zero gap is a real measurement (two rounds
+    // logged inside the same minute), a negative one is corrupt input. Tested on `gapMs`,
+    // not on `mins(gapMs)` — see the comment above the function for why.
+    const d = gapMs != null && gapMs >= 0 ? mins(gapMs) : null
+    if (round.headMoved === true) {
+      demotedCount += 1
+      if (d == null) demotedUnknown += 1
+      else demotedCost += d
+    } else if (d == null) {
+      costUnknown += 1
+    } else {
+      cost += d
+    }
+  }
+  const unowedCount = arr(hits).length - demotedCount
+  return {
+    costMinutes: costUnknown < unowedCount ? cost : null,
+    costUnknown,
+    demotedCostMinutes: demotedCount ? (demotedUnknown < demotedCount ? demotedCost : null) : null,
+    demotedUnknown,
+    demotedCount,
+  }
+}
+
+function findRoundsAfterPass(m) {
+  // A round the log itself proves was a rewritten head (`headMoved === true`) is probably a
+  // rebase — but the log cannot prove it WAS one, since closing a finding the reviewer itself
+  // called non-blocking also produces a new commit (why.md's epic-563 measurement: #572 had
+  // one of each). So a moved head is demoted, not dropped: still reported, ranked after the
+  // rounds the log cannot explain any other way, and labelled a probable rebase for a human
+  // to confirm. What ranks first is `false` (proven same head — the log rules OUT a rebase,
+  // so this is the residue) and `null` (headSha missing on one side, so the log cannot tell
+  // and falls back to reporting it, AC5). Kept as structured `{ unit, round }` pairs, not just
+  // rendered into `evidence` strings below: `round` still carries `at`/`priorAt`/`headSha`/
+  // `headMoved`, which is the seam a per-round cost fix (#761) reads rather than re-deriving
+  // this same filter over the raw manifest.
+  const hits = arr(m.units).flatMap((u) => roundsAfterPass(u).map((r) => ({ unit: u.id, round: r })))
+  if (!hits.length) return null
+  const undemoted = hits.filter((h) => h.round.headMoved !== true)
+  const demoted = hits.filter((h) => h.round.headMoved === true)
+  const ordered = [...undemoted, ...demoted]
+  const totalRounds = arr(m.units).reduce((n, u) => n + arr(u.rounds).length, 0)
+  // The cost is the gap between each reported round and the round immediately before it
+  // (`round.priorAt` -> `round.at`), bucketed by `headMoved` so a demoted round's
+  // queue-wait-heavy gap can never blend into the ranked `costMinutes` (#761). See
+  // `bucketRoundCost`'s own comment for why this replaced a per-unit span.
+  const bucketed = bucketRoundCost(hits)
+  return {
+    id: 'rounds-after-pass',
+    // The demotion has to reach the SIGNALS a reader skims, not just the evidence lines
+    // (#767). A finding whose actionable count is zero — every round after the PASS moved
+    // its head, so the log calls them all probable rebases — is not the run's worst problem,
+    // and leaving it HIGH puts it above findings that cost something real. `costMinutes`
+    // alone does not fix the order, because `profile()` sorts severity FIRST and only then
+    // by cost: on epic-563 the unowed bucket is empty, so cost collapses to null, and the
+    // finding still outranked a medium worth 189 minutes until severity moved too.
+    //
+    // Demoted to medium rather than low because the rounds are unconfirmed, not cleared —
+    // postmortem.md still obliges adjudicating every named round, demoted ones included.
+    severity: undemoted.length ? 'high' : 'medium',
+    costMinutes: bucketed.costMinutes,
+    costUnknown: bucketed.costUnknown,
+    demotedCostMinutes: bucketed.demotedCostMinutes,
+    demotedUnknown: bucketed.demotedUnknown,
+    demotedCount: bucketed.demotedCount,
+    // The leading integer counts what the finding is NAMED for — rounds bought after a PASS,
+    // all of them — and the split follows behind it (#767). Leading with the undemoted count
+    // instead made the headline contradict its own title: on epic-563 it read "0 of 8 review
+    // rounds were bought after a PASS on an unmoved head" when three rounds plainly were
+    // bought after a PASS, so the number a reader skims had quietly changed denominator and
+    // the founding "3 of 8" looked like it had fallen to zero. Same facts either way, same
+    // qualification, nothing dropped — but this order keeps the count continuous with the
+    // finding's name and puts the narrowing where it reads as a narrowing.
+    headline: demoted.length
+      ? `${hits.length} of ${totalRounds} review rounds were bought after a PASS — ${undemoted.length} on an unmoved head, ${demoted.length} on a moved head (probable rebases, unconfirmed)`
+      : `${hits.length} of ${totalRounds} review rounds were bought after a PASS`,
+    detail: 'A PASS is terminal (SKILL.md guarantee 3). A round logged after one owes a carve-out — red CI on that head, a rewritten head, or a landed contract revision. The log proves WHETHER a head moved but not WHY: a genuine rebase and a fix round that closes findings the reviewer itself called non-blocking both produce a new commit, so a moved head is reported here too — demoted below the rounds the log truly cannot explain, and labelled a probable rebase. "The notes inside the PASS were worth closing" is not a carve-out for either bucket.',
+    evidence: ordered.map(({ unit, round }) => `${unit} round ${round.round} (${round.verdict} @ ${round.headSha ?? '—'}) followed round ${round.passedAt.round}'s PASS${
+      round.headMoved === true ? ' — head moved, probably a rebase (unconfirmed — could be a fix round closing non-blocking notes)'
+        : round.headMoved === null ? ' — headSha missing on one side, could not adjudicate'
+        : ' — same head as the round before it'
+    }`),
+    recommendation: 'Deliver on the PASS and file the notes as deferrals[] with tracking issues. A round whose head moved is reported separately, demoted, and labelled a probable rebase — confirm which it was from the round log\'s own notes, since the signal cannot tell a rebase from a fix round that closes non-blocking findings; both move the head the same way. If a round on an unmoved head was still legitimate (a held verdict, a landed contract revision with no code delta), say so there too.',
+    rounds: ordered,
+  }
+}
+
+// Serialization, measured as the STAGGER BETWEEN UNITS rather than each unit's offset
+// from the run start. The difference matters and the naive version is a trap: the run's
+// end is defined by the last thing that happened, which is usually the last unit's last
+// round, so that unit's "offset from start" is ~100% of the run BY CONSTRUCTION. Reported
+// that way it looks like the worst finding in the run and means nothing. The gap from the
+// first unit's first round to the last unit's first round is a real quantity — it is how
+// much of the run had already elapsed before the roster was fully in flight — and no unit
+// can produce it trivially.
+function findStaggeredStart(m) {
+  const starts = arr(m.units).map((u) => ({ id: u.id, ...unitSpan(u) }))
+    .filter((s) => nonEmpty(s.firstRound))
+    .sort((a, b) => Date.parse(a.firstRound) - Date.parse(b.firstRound))
+  if (starts.length < 2) return null
+  const runLen = runMinutes(m)
+  const stagger = mins(ms(starts[0].firstRound, starts[starts.length - 1].firstRound))
+  if (!runLen || runLen <= 0 || stagger == null || stagger <= 0) return null
+  // Fires when the roster took longer than half the run to fully enter it. Below that the
+  // stagger is ordinary — units genuinely finish at different times.
+  if (stagger < runLen / 2) return null
+  return {
+    id: 'staggered-start',
+    severity: 'high',
+    costMinutes: stagger,
+    headline: `the roster took ${fmt(stagger)} of a ${fmt(runLen)} run to fully enter it`,
+    detail: 'Units that start far apart cannot overlap, so the run is serial in wall-clock even where the graph allows parallelism. Ask `run-state.mjs runnable <slug>` at every milestone: the bar is *pushed*, never *merged*, and a premise edge orders delivery rather than the build.',
+    evidence: starts.map((s) => `${s.id} first round at +${fmt(mins(ms(starts[0].firstRound, s.firstRound)))} after the first unit's`),
+    recommendation: 'For each late unit, replay the manifest through `runnable` at the point it was queued. If it says ADMIT NOW, the unit was not blocked — the scheduler was simply not consulted.',
+  }
+}
+
+function findCapBelowDefault(m) {
+  const cap = m.inFlightCap
+  if (!Number.isSafeInteger(cap) || cap >= DEFAULT_IN_FLIGHT_CAP) return null
+  const roster = arr(m.units).length
+  return {
+    id: 'cap-below-default',
+    severity: roster > cap ? 'high' : 'low',
+    costMinutes: null,
+    headline: `inFlightCap was ${cap} on a roster of ${roster}`,
+    detail: `The cap is ${DEFAULT_IN_FLIGHT_CAP} on every repo and the loop does not choose it. It bounds disk and dependency-install cost, never correctness, and it is read once and then never revisited — so a low value written in the first minutes silently prices the whole run.`,
+    evidence: [`inFlightCap: ${cap}`, `units: ${roster}`],
+    recommendation: 'Drop the field unless a human measured a slow install here. Replay `runnable` at both values to see what the difference actually admitted.',
+  }
+}
+
+function findUnrecordedPush(m) {
+  const stranded = arr(m.units).filter((u) => !isResolvedUnit(u) && !nonEmpty(u.pushedSha) && !nonEmpty(u.pr))
+  const missingSha = arr(m.units).filter((u) => !nonEmpty(u.pushedSha))
+  if (!missingSha.length) return null
+  return {
+    id: 'pushed-sha-unrecorded',
+    severity: stranded.length ? 'high' : 'medium',
+    costMinutes: null,
+    headline: `${missingSha.length} of ${arr(m.units).length} units never recorded pushedSha`,
+    detail: '`pushedSha` is what makes a unit\'s dependents runnable. A recorded `pr` covers the same ground (a PR cannot exist over an unpushed head), so a unit with neither is the one that actually strands its dependents.',
+    evidence: [
+      ...missingSha.map((u) => `${u.id}: pushedSha unrecorded${nonEmpty(u.pr) ? ` (pr ${u.pr} covers it)` : ''}`),
+      ...stranded.map((u) => `${u.id}: NEITHER pushedSha nor pr — dependents cannot be released`),
+    ],
+    recommendation: 'Derive it rather than remember it: read `gh pr view <pr> --json headRefOid` in the turn the producer returns and upsert it with the PR number.',
+  }
+}
+
+function deliveryComponents(m) {
+  const units = arr(m.units)
+  const byId = new Map(units.map((unit) => [unit.id, unit]))
+  const declared = arr(m.components)
+  const declaredMembers = (memberRefs) => {
+    const seen = new Set()
+    return (Array.isArray(memberRefs) ? memberRefs : []).map((entry, index) => {
+      const id = typeof entry === 'string' && nonEmpty(entry)
+        ? entry
+        : isObject(entry) && nonEmpty(entry.id) ? entry.id : null
+      const duplicate = id != null && seen.has(id)
+      if (id != null) seen.add(id)
+      const valid = id != null
+      const unit = valid ? byId.get(id) ?? null : null
+      return { index, id, valid, resolved: unit != null, duplicate, unit }
+    })
+  }
+  if (!declared.length) return deriveComponents(units).map((component) => ({
+    ...component,
+    memberRefs: component.units.map((unit, index) => ({
+      index, id: unit.id, valid: true, resolved: true, duplicate: false, unit,
+    })),
+  }))
+  const claimed = new Set()
+  const groups = declared.map((component) => {
+    const members = declaredMembers(component.units)
+    for (const member of members) if (member.unit != null) claimed.add(member.unit.id)
+    return { ...component, id: component.id, memberRefs: members, units: members.map((member) => member.unit).filter(Boolean) }
+  })
+  for (const unit of units) if (!claimed.has(unit.id)) groups.push({
+    id: `component:${unit.id}`, units: [unit],
+    memberRefs: [{ index: 0, id: unit.id, valid: true, resolved: true, duplicate: false, unit }],
+  })
+  return groups
+}
+
+function terminalUnitPass(unit) {
+  const rounds = arr(unit.rounds)
+  const firstPassIndex = rounds.findIndex((round) => round.verdict === 'PASS' && nonEmpty(round.at))
+  if (firstPassIndex < 0) return null
+  let readyPass = rounds[firstPassIndex].at
+  for (let index = firstPassIndex + 1; index < rounds.length; index++) {
+    const round = rounds[index]
+    if (round.verdict !== 'PASS' || !nonEmpty(round.at)) continue
+    const reconstructedReopen = rounds.slice(firstPassIndex + 1, index).some((entry) => entry.verdict !== 'PASS')
+    if (nonEmpty(round.reopenReason) || reconstructedReopen) readyPass = round.at
+  }
+  return readyPass
+}
+const COMPONENT_PHASES = [
+  ['unit-pass-to-complete-candidate', 'engineering/integration', 'component assembly'],
+  ['complete-candidate-to-freeze', 'engineering/integration', 'integrated verification before freeze'],
+  ['freeze-to-terminal-authorization', 'published CI', 'exact-head published CI and terminal authorization'],
+  ['terminal-authorization-to-queue-request', 'queue', 'queue request'],
+  ['queue-request-to-admission', 'queue', 'queue admission'],
+  ['admission-to-merge', 'queue/CI', 'queue waiting and speculative queue CI'],
+  ['merge-to-outcome-recorded', 'bookkeeping', 'delivery outcome recording'],
+]
+
+function latestAt(entries) {
+  const stamped = arr(entries).filter((entry) => nonEmpty(entry.at) && Number.isFinite(Date.parse(entry.at)))
+  return stamped.length ? stamped.reduce((latest, entry) => Date.parse(entry.at) > Date.parse(latest.at) ? entry : latest) : null
+}
+
+function componentCandidateClocks(component) {
+  const candidate = isObject(component?.candidate) ? component.candidate : {}
+  const generation = Number.isSafeInteger(candidate.generation) ? candidate.generation : null
+  const members = Array.isArray(component.memberRefs)
+    ? component.memberRefs
+    : component.units.map((unit, index) => ({ index, id: unit.id, valid: true, resolved: true, duplicate: false, unit }))
+  const memberIds = members.map((member) => member.id)
+  const validMembership = members.length > 0 && members.every((member) => member.valid && member.resolved && !member.duplicate)
+  const updates = arr(candidate.updates).filter((update) => generation == null || update.generation === generation)
+  const completeUpdate = (validMembership && updates.find((update) => Array.isArray(update.includedUnits)
+    && update.includedUnits.length === memberIds.length
+    && memberIds.every((id) => update.includedUnits.includes(id)))) ?? null
+  const frozen = candidate.frozen?.generation === generation || generation == null ? candidate.frozen : null
+  const authorization = latestAt(arr(candidate.authorizations)
+    .filter((entry) => generation == null || entry.generation === generation))
+  return {
+    completeCandidateAt: nonEmpty(completeUpdate?.at) ? completeUpdate.at : null,
+    frozenAt: nonEmpty(frozen?.at) ? frozen.at : null,
+    authorizedAt: nonEmpty(authorization?.at) ? authorization.at : null,
+  }
+}
+
+function componentDeliveryClocks(component, members, authorizedAt) {
+  const validMembership = members.length > 0 && members.every((member) => member.valid !== false && member.resolved !== false && !member.duplicate)
+  const canonical = isObject(component?.delivery) ? component.delivery : null
+  if (canonical) {
+    const attempts = arr(canonical.attempts)
+      .filter((attempt) => attempt.generation === canonical.generation && nonEmpty(attempt.at) && Number.isFinite(Date.parse(attempt.at)))
+      .sort((left, right) => Date.parse(left.at) - Date.parse(right.at))
+    const observations = arr(canonical.observations)
+      .filter((observation) => observation.generation === canonical.generation && nonEmpty(observation.at) && Number.isFinite(Date.parse(observation.at)))
+      .sort((left, right) => Date.parse(left.at) - Date.parse(right.at))
+    const request = attempts.find((attempt) => attempt.action === 'enqueue') ?? null
+    const admitted = observations.find((observation) => !['not-enqueued', 'waiting-for-queue-conditions'].includes(observation.queueState)) ?? null
+    return {
+      queueRequestedAt: validMembership ? request?.at ?? null : null,
+      admittedAt: validMembership ? admitted?.at ?? null : null,
+      admissionStatus: validMembership && admitted ? 'measured' : 'unknown',
+      mergedAt: validMembership && canonical.outcome === 'merged' ? (canonical.mergedAt ?? canonical.outcomeAt ?? null) : null,
+      outcomeWrittenAt: validMembership && canonical.outcome === 'merged' ? canonical.outcomeAt ?? null : null,
+    }
+  }
+  const memberQueueEvidence = members.map((member) => {
+    const unit = member.unit
+    const attempts = arr(unit?.delivery?.attempts)
+      .filter((attempt) => nonEmpty(attempt.at) && Number.isFinite(Date.parse(attempt.at)))
+      .sort((left, right) => Date.parse(left.at) - Date.parse(right.at))
+    const afterAuthorization = nonEmpty(authorizedAt)
+      ? attempts.filter((attempt) => Date.parse(attempt.at) >= Date.parse(authorizedAt))
+      : []
+    const request = afterAuthorization.find((attempt) => attempt.action === 'enqueue' && attempt.outcome === 'requested') ?? null
+    const waiting = afterAuthorization.filter((attempt) => attempt.action === 'enqueue' && attempt.outcome === 'waiting')
+    const admission = request == null ? null : waiting.find((attempt) => Date.parse(attempt.at) >= Date.parse(request.at)) ?? null
+    return {
+      queueRequestedAt: request?.at ?? null,
+      admittedAt: admission?.at ?? null,
+      admissionStatus: admission != null ? 'measured' : request != null && waiting.length ? 'out-of-order' : 'unknown',
+    }
+  })
+  const requested = memberQueueEvidence.map((evidence) => evidence.queueRequestedAt).filter(nonEmpty)
+  const admitted = memberQueueEvidence.map((evidence) => evidence.admittedAt).filter(nonEmpty)
+  const spans = members.map((member) => member.unit == null ? { delivered: null, outcomeWritten: null } : unitSpan(member.unit))
+  const merged = spans.map((span) => span.delivered).filter(nonEmpty)
+  const outcomeWritten = spans.map((span) => span.outcomeWritten).filter(nonEmpty)
+  return {
+    queueRequestedAt: validMembership && requested.length === memberQueueEvidence.length ? requested.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest) : null,
+    admittedAt: validMembership && admitted.length === memberQueueEvidence.length ? admitted.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest) : null,
+    admissionStatus: validMembership && admitted.length === memberQueueEvidence.length
+      ? 'measured'
+      : validMembership && memberQueueEvidence.some((evidence) => evidence.admissionStatus === 'out-of-order') ? 'out-of-order' : 'unknown',
+    mergedAt: validMembership && merged.length === spans.length ? merged.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest) : null,
+    outcomeWrittenAt: validMembership && outcomeWritten.length === spans.length ? outcomeWritten.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest) : null,
+  }
+}
+
+function componentPhase(id, category, label, fromAt, toAt, missingStatus = 'unknown') {
+  if (!nonEmpty(fromAt) || !nonEmpty(toAt)) {
+    return { id, category, label, fromAt: fromAt ?? null, toAt: toAt ?? null, durationMinutes: null, status: missingStatus }
+  }
+  const durationMs = ms(fromAt, toAt)
+  if (durationMs == null || durationMs < 0) {
+    return { id, category, label, fromAt, toAt, durationMinutes: null, status: 'out-of-order' }
+  }
+  return { id, category, label, fromAt, toAt, durationMinutes: mins(durationMs), status: 'measured' }
+}
+
+// Stable machine-readable diagnostic for component lifecycle attribution. This uses only
+// recorded clocks: a missing or backwards clock is named instead of being zeroed or inferred.
+export function componentTimelinesFor(manifest = {}) {
+  const source = isObject(manifest) ? manifest : {}
+  return deliveryComponents(source).map((component) => {
+    const members = component.memberRefs ?? component.units.map((unit, index) => ({ index, id: unit.id, valid: true, resolved: true, duplicate: false, unit }))
+    const terminalPasses = members.map((member) => member.unit == null ? null : terminalUnitPass(member.unit))
+    const validMembership = members.length > 0
+      && members.every((member) => member.valid !== false && member.resolved !== false && !member.duplicate)
+    const readyAt = validMembership && terminalPasses.length && terminalPasses.every(nonEmpty)
+      ? terminalPasses.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest)
+      : null
+    const candidate = componentCandidateClocks(component)
+    const delivery = componentDeliveryClocks(component, members, candidate.authorizedAt)
+    const clocks = [readyAt, candidate.completeCandidateAt, candidate.frozenAt, candidate.authorizedAt,
+      delivery.queueRequestedAt, delivery.admittedAt, delivery.mergedAt, delivery.outcomeWrittenAt]
+    const phases = COMPONENT_PHASES.map(([id, category, label], index) => componentPhase(
+      id, category, label, clocks[index], clocks[index + 1],
+      id === 'queue-request-to-admission' ? delivery.admissionStatus : 'unknown',
+    ))
+    const aggregate = componentPhase('component-ready-to-merge', 'aggregate', 'component-ready PASS to merge', readyAt, delivery.mergedAt)
+    const diagnostics = phases.filter((phase) => phase.status !== 'measured').map((phase) => ({
+      id: phase.status === 'out-of-order' ? 'out-of-order-clock' : 'missing-clock',
+      phase: phase.id,
+      detail: phase.status === 'out-of-order'
+        ? nonEmpty(phase.fromAt) && nonEmpty(phase.toAt)
+          ? `${phase.fromAt} is later than ${phase.toAt}; attribution is withheld.`
+          : 'Incompatible lifecycle clock ordering; attribution is withheld.'
+        : 'Missing lifecycle clock; attribution is unknown.',
+    }))
+    if (aggregate.status === 'out-of-order') diagnostics.push({
+      id: 'out-of-order-clock', phase: aggregate.id,
+      detail: `${aggregate.fromAt} is later than ${aggregate.toAt}; aggregate duration is withheld.`,
+    })
+    return {
+      id: component.id,
+      // `members` remains the legacy normalized-ID projection. `declaredMembers` is the
+      // complete diagnostic declaration, including invalid and duplicate slots.
+      members: members.map((member) => member.id).filter(nonEmpty),
+      declaredMembers: members.map(({ index, id, valid, resolved, duplicate }) => ({
+        index,
+        id: id ?? null,
+        valid: valid === true,
+        resolved: resolved === true,
+        duplicate: duplicate === true,
+      })),
+      aggregate: { startAt: aggregate.fromAt, endAt: aggregate.toAt, durationMinutes: aggregate.durationMinutes, status: aggregate.status },
+      phases,
+      diagnostics,
+    }
+  })
+}
+
+function renderComponentTimelines(timelines) {
+  if (!timelines.length) return []
+  const rows = ['', '  COMPONENT TIMELINES']
+  for (const timeline of timelines) {
+    const memberSlots = timeline.declaredMembers.map((member) => {
+      const value = member.id ?? '<invalid>'
+      const status = !member.valid ? 'invalid'
+        : member.duplicate ? 'duplicate'
+          : !member.resolved ? 'missing' : 'resolved'
+      return `[${member.index}] ${value} (${status})`
+    }).join('; ')
+    rows.push(`  ${timeline.id}: ${timeline.members.join(', ')} · aggregate ${timeline.aggregate.status === 'measured' ? fmt(timeline.aggregate.durationMinutes) : 'unknown'} · declared slots: ${memberSlots}`)
+    for (const phase of timeline.phases) {
+      const duration = phase.status === 'measured' ? fmt(phase.durationMinutes) : phase.status
+      rows.push(`    ${phase.category}: ${phase.label} — ${duration}`)
+    }
+    for (const diagnostic of timeline.diagnostics) rows.push(`    diagnostic [${diagnostic.id}] ${diagnostic.phase}: ${diagnostic.detail}`)
+  }
+  return rows
+}
+
+function findDeliveryWait(m) {
+  // Delivery is component-shaped. A member of a co-delivery component is not independently
+  // ready at its own PASS, so charging every early member until the shared merge multiplies
+  // one integration interval by the component size (epic-892: eight findings for one wait).
+  // The component becomes ready at its latest member PASS. Singleton components retain the
+  // historical unit clock. Every member must carry a real delivery clock; partial delivery
+  // yields no timing claim rather than selecting whichever timestamp happens to exist.
+  const waits = deliveryComponents(m).map((component) => {
+    const members = component.memberRefs ?? component.units.map((unit, index) => ({ index, id: unit.id, valid: true, resolved: true, duplicate: false, unit }))
+    const validMembership = members.length > 0 && members.every((member) => member.valid !== false && member.resolved !== false && !member.duplicate)
+    const spans = members.map((member) => {
+      const unit = member.unit
+      if (unit == null) return { id: member.id, terminalPass: null, delivered: null }
+      const span = unitSpan(unit, m)
+      const rounds = arr(unit.rounds)
+      const firstPassIndex = rounds.findIndex((round) => round.verdict === 'PASS' && nonEmpty(round.at))
+      let readyPass = firstPassIndex >= 0 ? rounds[firstPassIndex].at : null
+      // A PASS is terminal unless a typed carve-out reopened it. Legacy logs may not carry
+      // reopenReason, but an intervening non-PASS verdict proves the unit re-entered the
+      // loop. Consecutive PASS rounds do not reset readiness: those are exactly the
+      // rounds-after-PASS waste this profiler reports elsewhere.
+      for (let index = firstPassIndex + 1; index >= 0 && index < rounds.length; index++) {
+        const round = rounds[index]
+        if (round.verdict !== 'PASS' || !nonEmpty(round.at)) continue
+        const interveningNonPass = rounds.slice(firstPassIndex + 1, index).some((entry) => entry.verdict !== 'PASS')
+        if (nonEmpty(round.reopenReason) || interveningNonPass) readyPass = round.at
+      }
+      return { id: unit.id, ...span, terminalPass: readyPass }
+    })
+    if (!validMembership || !spans.length || spans.some((span) => !nonEmpty(span.terminalPass) || !nonEmpty(span.delivered))) return null
+    const readyAt = spans.reduce((latest, span) => Date.parse(span.terminalPass) > Date.parse(latest) ? span.terminalPass : latest, spans[0].terminalPass)
+    const deliveredAt = spans.reduce((latest, span) => Date.parse(span.delivered) > Date.parse(latest) ? span.delivered : latest, spans[0].delivered)
+    const wait = mins(ms(readyAt, deliveredAt))
+    if (wait == null || wait <= 60) return null
+    return { id: component.id, members: spans.map((span) => span.id), readyAt, deliveredAt, wait }
+  }).filter(Boolean)
+  if (!waits.length) return null
+  waits.sort((a, b) => b.wait - a.wait)
+  const unitCount = waits.reduce((count, wait) => count + wait.members.length, 0)
+  return {
+    id: 'delivery-wait',
+    severity: 'medium',
+    costMinutes: waits[0].wait,
+    headline: `${waits.length} component(s) covering ${unitCount} unit(s) waited over an hour after component readiness`,
+    detail: 'Time from a component becoming ready (its latest member PASS) to its merge is integration, terminal review, CI repair, and queue time. It is one interval per deliverable, not one interval per member. Distinct from outcome-write-lag: that one is late bookkeeping after the PR already merged.',
+    evidence: waits.map((wait) => wait.members.length === 1
+      ? `${wait.members[0]}: ${fmt(wait.wait)} from first PASS to delivery`
+      : `${wait.id}: ${fmt(wait.wait)} from component-ready PASS to delivery (${wait.members.length} units: ${wait.members.join(', ')})`),
+    recommendation: 'Split the component interval using candidate update/freeze/authorization and delivery timestamps where recorded: optimize assembly or integrated review before authorization, and queue mechanics after authorization. Revisit component boundaries only when symbol/assembly evidence says members were bundled unnecessarily; premise edges order delivery without bundling.',
+  }
+}
+
+// #791 / issue-664 / identity#669: PR already MERGED (mergedAt recorded), but
+// record-delivery-* was written hours later after a human progress ping. That lag is
+// bookkeeping, not queue wait and not co-delivery hold. Stable id for the series index.
+function findOutcomeWriteLag(m) {
+  const canonicalMembers = new Set()
+  const componentRows = arr(m.components).map((component) => {
+    const delivery = isObject(component.delivery) ? component.delivery : null
+    if (!delivery) return null
+    for (const id of Array.isArray(component.units) ? component.units : []) if (nonEmpty(id)) canonicalMembers.add(id)
+    if (delivery.outcome !== 'merged' || !nonEmpty(delivery.mergedAt) || !nonEmpty(delivery.outcomeAt)) return null
+    const lag = mins(ms(delivery.mergedAt, delivery.outcomeAt))
+    if (lag == null || lag <= 60) return null
+    const members = arr(m.units).filter((unit) => (Array.isArray(component.units) ? component.units : []).includes(unit.id))
+    const passes = members.map(terminalUnitPass).filter(nonEmpty)
+    const readyAt = passes.length === members.length && passes.length
+      ? passes.reduce((latest, at) => Date.parse(at) > Date.parse(latest) ? at : latest)
+      : null
+    const realWait = readyAt ? mins(ms(readyAt, delivery.mergedAt)) : null
+    if (realWait != null && realWait > 60) return null
+    return { id: component.id, lag, mergedAt: delivery.mergedAt, written: delivery.outcomeAt }
+  }).filter(Boolean)
+  const legacyRows = arr(m.units).filter((unit) => !canonicalMembers.has(unit.id)).map((unit) => {
+    const span = unitSpan(unit, m)
+    if (!span.mergedAt || !span.outcomeWritten) return null
+    const lag = mins(ms(span.mergedAt, span.outcomeWritten))
+    if (lag == null || lag <= 60) return null
+    const realWait = span.firstPass && span.delivered ? mins(ms(span.firstPass, span.delivered)) : null
+    if (realWait != null && realWait > 60) return null
+    return { id: unit.id, lag, mergedAt: span.mergedAt, written: span.outcomeWritten }
+  }).filter(Boolean)
+  const lags = [...componentRows, ...legacyRows]
+  if (!lags.length) return null
+  lags.sort((a, b) => b.lag - a.lag)
+  return {
+    id: 'outcome-write-lag',
+    severity: 'low',
+    costMinutes: lags[0].lag,
+    headline: `${lags.length} unit(s) had delivery.outcome written long after the PR already merged`,
+    detail: 'The PR reached targetBranch (delivery.mergedAt) well before record-delivery-attempt/outcome ran. That gap is bookkeeping lag, not queue wait and not a co-delivery hold — typically hybrid/auto merge unobserved until a human asked for progress (issue-664 / identity#669).',
+    evidence: lags.map((w) => `${w.id}: mergedAt ${w.mergedAt} → outcome written ${w.written} (${fmt(w.lag)} lag)`),
+    recommendation: 'Launch the delivery watch in the same turn as PASS on enqueueTrigger ∈ {hybrid, auto}; do not wait for an explicit @mergifyio queue. On watch exit 4 with reason stall-while-queued, re-observe once (gh pr view) and relaunch the watch — do not leave the unit undelivered until a human asks for progress. Record mergedAt on record-delivery-outcome so the metric has a source of truth.',
+  }
+}
+
+const FINDERS = [findRoundsAfterPass, findStaggeredStart, findCapBelowDefault, findUnrecordedPush, findDeliveryWait, findOutcomeWriteLag]
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 }
+
+// The generic pass. Both orchestrators share the ranking, the renderer, the persistence and
+// the cross-run series; what differs is WHICH questions get asked of the manifest and how
+// the one-line summary reads. So the finder set and the summary are injected, and this
+// function knows nothing about units or release steps.
+//
+// `metrics` is the per-kind headline block. It goes into the index line verbatim, which is
+// what lets one series carry both kinds without either pretending to be the other — a
+// release has no `inFlightCap` and a delivery run has no `step`, and forcing a shared column
+// set would mean writing nulls that read as measurements.
+export function profile(manifest = {}, opts = {}) {
+  const m = isObject(manifest) ? manifest : {}
+  const finders = Array.isArray(opts.finders) ? opts.finders : FINDERS
+  const summarise = typeof opts.summary === 'function' ? opts.summary : deliverySummary
+  const findings = finders.map((f) => f(m)).filter(Boolean)
+    .sort((a, b) => (SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
+      || ((b.costMinutes ?? 0) - (a.costMinutes ?? 0)))
+  const { kind, summaryLine, metrics, blindSpots } = summarise(m)
+  return { kind, runSlug: m.runSlug ?? null, summaryLine, metrics, blindSpots, findings }
+}
+
+function deliverySummary(m) {
+  const units = arr(m.units)
+  const metrics = {
+    units: units.length,
+    totalRounds: units.reduce((n, u) => n + arr(u.rounds).length, 0),
+    runMinutes: runMinutes(m),
+    inFlightCap: m.inFlightCap ?? DEFAULT_IN_FLIGHT_CAP,
+  }
+  return {
+    kind: 'delivery',
+    metrics,
+    summaryLine: `${metrics.units} units · ${metrics.totalRounds} review rounds · ${fmt(metrics.runMinutes)} wall-clock · inFlightCap ${metrics.inFlightCap}`,
+    blindSpots: 'per-spawn wall-time, context growth, and orchestrator idle windows — read the session transcript for those',
+  }
+}
+
+// Kept as it was: the delivery pass's public entry point, and the shape its tests and the
+// index have always seen. The metrics are spread flat here for exactly that reason.
+export function postmortem(manifest = {}) {
+  const p = profile(manifest)
+  return { runSlug: p.runSlug, ...p.metrics, componentTimelines: componentTimelinesFor(manifest), findings: p.findings }
+}
+
+// A finding's cost, rendered for a human. Every finder but `findRoundsAfterPass` sets only
+// `costMinutes`, and for those this renders exactly as before — `~5m` — so the common case
+// does not get noisier to serve the rare one (#780). `costUnknown`/`demotedCostMinutes`/
+// `demotedUnknown`/`demotedCount` only exist on `findRoundsAfterPass`'s output: when present,
+// the excluded and demoted quantities are named explicitly, because #761's AC3 forbids an
+// unpriceable round reading as priced, and that requirement was closed at `bucketRoundCost`
+// (the data layer) while staying open here — the layer a human actually reads (#780).
+// `!= null`, never truthiness: #761 made a genuine `costMinutes: 0` reachable, and
+// `f.costMinutes ? … : ''` rendered a real zero byte-identical to an unpriced finding.
+//
+// `costMinutes: null` is ambiguous on its own — it means either "some undemoted rounds
+// exist but none could be timed" (costUnknown > 0) or "there are no undemoted rounds at
+// all, e.g. every hit was demoted" (costUnknown === 0, since `bucketRoundCost` only ever
+// increments it for an undemoted hit). Only the first is genuinely unpriceable; the second
+// has nothing to report in the ranked bucket, and saying "unpriceable" there would claim a
+// failure that never happened — epic-563's fixture is exactly this case (0 undemoted hits,
+// 3 demoted), and the ranked bucket should say nothing while the demoted one still does.
+function formatCost(f) {
+  const unknown = f.costUnknown || 0
+  const demotedCount = f.demotedCount || 0
+  if (!unknown && !demotedCount) return f.costMinutes != null ? `~${fmt(f.costMinutes)}` : null
+  const ranked = []
+  if (f.costMinutes != null) ranked.push(`~${fmt(f.costMinutes)} ranked`)
+  if (unknown) ranked.push(`${unknown} unpriceable`)
+  const parts = ranked.length ? [ranked.join(', ')] : []
+  if (demotedCount) {
+    // Symmetric with the ranked branch above, and for the same reason: a demoted round can
+    // be PARTIALLY unpriceable — `demotedCostMinutes` is the sum of the ones that could be
+    // timed, `demotedUnknown` is how many could not (0 when every demoted round priced, ===
+    // demotedCount when none did — that all-unpriceable case is the `null` branch below).
+    // Reading `demotedCostMinutes` whole without naming `demotedUnknown` reproduces #780's
+    // own opening defect one bucket over: a subtotal renders as if it covered everything it
+    // was computed from, when part of what it was computed from was never priced at all.
+    const demotedUnknown = f.demotedUnknown || 0
+    parts.push(f.demotedCostMinutes != null
+      ? (demotedUnknown ? `~${fmt(f.demotedCostMinutes)} demoted, ${demotedUnknown} unpriceable` : `~${fmt(f.demotedCostMinutes)} demoted`)
+      : 'demoted cost unpriceable')
+  }
+  // `parts` is never empty here: the guard above already returned for `!unknown &&
+  // !demotedCount`, and every remaining path pushes at least one entry — `unknown` truthy
+  // always pushes into `ranked` regardless of `costMinutes`, and `demotedCount` truthy
+  // always pushes its own entry above.
+  return parts.join('; ')
+}
+
+export function renderProfile(p) {
+  const rows = [
+    `POST-MORTEM — ${p.runSlug ?? '(unnamed run)'}`,
+    `  ${p.summaryLine}`,
+    '',
+  ]
+  if (!p.findings.length) {
+    rows.push('  No findings. The record holds nothing this pass knows how to fault —')
+    rows.push('  which is a statement about THIS pass, not a clean bill of health: it reads')
+    rows.push(`  ${p.source ?? 'the run manifest'} only, so it cannot see ${p.blindSpots}.`)
+    return `${rows.join('\n')}\n`
+  }
+  for (const f of p.findings) {
+    const cost = formatCost(f)
+    rows.push(`  [${f.severity.toUpperCase()}] ${f.headline}${cost ? `  (${cost})` : ''}`)
+    rows.push(`      ${f.detail}`)
+    for (const e of f.evidence) rows.push(`        · ${e}`)
+    rows.push(`      → ${f.recommendation}`)
+    rows.push('')
+  }
+  rows.push(`  Computed from ${p.source ?? 'the run manifest'}. What it cannot see: ${p.blindSpots}.`)
+  return `${rows.join('\n')}\n`
+}
+
+export function renderPostmortem(manifest = {}) {
+  const p = profile(manifest)
+  const base = renderProfile(p).trimEnd().split('\n')
+  base.push(...renderComponentTimelines(componentTimelinesFor(manifest)))
+  return `${base.join('\n')}\n`
+}
+
+// The issue body. The post-mortem's output is worth nothing if it lands in a handoff
+// nobody re-reads, so the step ends by filing it — one issue per run, against the skill,
+// with the measurements inline. Rendered here rather than composed by the caller for the
+// same reason the spawn contract is: a composed one decays across runs.
+export function renderProfileIssue(p, skillName = 'resolve-issues') {
+  const title = `${skillName} post-mortem: ${p.runSlug ?? 'run'} (${p.summaryLine.split(' · ').slice(0, 2).join(', ')}, ${p.findings.length} findings)`
+  const body = [
+    `Automated post-mortem of \`${p.runSlug ?? '(unnamed run)'}\`. Every number below is computed from the run manifest by \`${skillName}/scripts/postmortem.mjs\`; none of it is recalled.`,
+    '',
+    `**Run:** ${p.summaryLine}`,
+    '',
+    ...(p.findings.length ? p.findings.flatMap((f) => {
+      const cost = formatCost(f)
+      return [
+        `### ${f.headline}`,
+        '',
+        `**Severity:** ${f.severity}${cost ? ` · **measured cost:** ${cost}` : ''}`,
+        '',
+        f.detail,
+        '',
+        ...f.evidence.map((e) => `- ${e}`),
+        '',
+        `**Proposed change:** ${f.recommendation}`,
+        '',
+      ]
+    }) : ['No findings — the manifest holds nothing this pass knows how to fault.', '']),
+    '---',
+    '',
+    `Scope note: this pass reads the run manifest only, so it cannot see ${p.blindSpots}. A finding it did *not* raise is not evidence those were fine.`,
+  ].join('\n')
+  return { title, body }
+}
+
+export function renderPostmortemIssue(manifest = {}) {
+  const rendered = renderProfileIssue(profile(manifest))
+  const timelines = componentTimelinesFor(manifest)
+  if (!timelines.length) return rendered
+  return {
+    ...rendered,
+    body: `${rendered.body}\n\n## Component Timelines\n\n${renderComponentTimelines(timelines).map((line) => line.trim()).join('\n')}`,
+  }
+}
+
+// ---- persistence ----
+//
+// Three artifacts, because three different readers want this and none of them wants the
+// other's format:
+//
+//   <slug>.json   the structured profile — what a later diff or a script reads
+//   <slug>.txt    the rendered report — what a human opens six weeks later
+//   index.jsonl   one line per save — the CROSS-RUN series, which is the whole point
+//
+// The index is APPEND-ONLY and deliberately not deduplicated. Re-running the pass on the
+// same slug appends a second line, and that is a fact worth keeping (it dates the re-read),
+// not a bug to suppress. Readers take the last entry per slug. Append rather than
+// read-modify-write for the reason run-state.mjs already documents about `writeManifest`:
+// nothing guards a read-modify-write here either, and two runs finishing together would
+// silently drop one. A single `appendFileSync` of one line does not have that problem.
+//
+// NEVER THROWS. A failed save must not take the handoff down with it — the profile is a
+// diagnostic, and a read-only or full disk is a reason to report a degraded save, not to
+// fail a run whose units all merged. Returns { saved, paths, error }.
+// Takes a PROFILE, not a manifest, so both orchestrators write one series in one format.
+// The index line carries `kind` plus the per-kind `metrics` block rather than a flattened
+// union of both schemas: a release has no `inFlightCap` and a delivery run has no `step`,
+// and a shared column set would mean writing nulls that read as measurements.
+export function saveProfile(p, env = process.env, now = new Date()) {
+  const paths = postmortemPaths(p?.runSlug, env)
+  const savedAt = now.toISOString()
+  try {
+    fs.mkdirSync(paths.dir, { recursive: true })
+    fs.writeFileSync(paths.json, `${JSON.stringify({ ...p, savedAt }, null, 2)}\n`)
+    fs.writeFileSync(paths.text, renderProfile(p))
+    // Narrow on purpose — the full findings live in the JSON, and narrowness is what keeps
+    // the series greppable at 200 runs. `costUnknown`/`demotedCostMinutes`/`demotedUnknown`
+    // join `costMinutes` here for the same reason they now reach the renderers (#780): a
+    // trend series that carries the ranked cost but drops what was excluded from it would
+    // let the same "excluded reads as priced" defect creep back into a longitudinal read,
+    // even though `renderProfile`/`renderProfileIssue` now say so per-run. Still numeric
+    // fields, still no prose — the "stay narrow" invariant the assertion below checks is
+    // about `detail`/`evidence`, not about the count of numeric columns.
+    fs.appendFileSync(paths.index, `${JSON.stringify({
+      savedAt,
+      kind: p.kind ?? 'delivery',
+      runSlug: p.runSlug,
+      metrics: p.metrics ?? {},
+      findings: (p.findings ?? []).map((f) => ({
+        id: f.id,
+        severity: f.severity,
+        costMinutes: f.costMinutes ?? null,
+        costUnknown: f.costUnknown ?? 0,
+        demotedCostMinutes: f.demotedCostMinutes ?? null,
+        demotedUnknown: f.demotedUnknown ?? 0,
+        // `demotedCount` is the denominator `demotedUnknown` is a count OUT OF — the
+        // renderers use this same pair (formatCost reads both) to tell "no demoted rounds
+        // at all" (demotedCount: 0) from "some demoted rounds, none unpriceable"
+        // (demotedCount > 0, demotedUnknown: 0) apart. Carrying demotedUnknown without it
+        // is an excluded count with no denominator.
+        demotedCount: f.demotedCount ?? 0,
+      })),
+    })}\n`)
+    return { saved: true, paths, error: null }
+  } catch (e) {
+    return { saved: false, paths, error: e?.message ?? String(e) }
+  }
+}
+
+export function savePostmortem(manifest = {}, env = process.env, now = new Date()) {
+  return saveProfile(profile(manifest), env, now)
+}
+
+// Is every unit terminal enough for completion-phase reporting? This remains a pure
+// predicate: progress and next may read it, but only the dedicated finalize transition
+// can authorize completion. The explicit postmortem diagnostic is also read-only.
+export function runIsComplete(manifest = {}) {
+  const units = arr(manifest?.units)
+  if (!units.length) return false
+  return units.every((unit) => terminalDisposition(unit) !== null)
+}