Skip to content

doctor reports lost decisions for pending captures that never held one #710

Description

@MongLong0214

Found by running doctor on this repository.

warn  pending captures — 4 capture(s) can no longer apply — their base commit is no
      longer HEAD; oldest from 2026-08-13T12:50:26.870Z. A staged record binds to the
      tree it was prepared for and is skipped once that tree moves, so these decisions
      were never written to the history (#458)

The four it is describing:

NONCE     PHASE     RECORDS  VALIDATION  AGE   BASE      FLAGS
ba54a69c  prepared  0        -           3d    ff333338  stale
bd065cf2  prepared  0        -           3d    9c4d25aa  stale
464b4c13  prepared  0        -           3d    9c4d25aa  stale
e8eb71c6  prepared  0        -           3d    9c4d25aa  stale

Zero records, none staged. Nothing was drafted, so no decision was lost. The warning says one was — four times.

Where it comes from

src/commands/doctor/checks/capture-pending-backlog.ts already draws the distinction that matters:

const lost = stranded.filter((transaction) => transaction.phase === 'staged');   // :131

const detail = lost.length > 0
  ? `${lost.length} staged capture(s) expired before reaching a commit and were dropped` + 
  : `${stranded.length} capture(s) can no longer apply — their base commit is no longer HEAD`;   // :139-145

Both branches are accurate. The sentence appended after them is not conditional:

`${detail}; oldest from ${oldest}. ` +
  'A staged record binds to the tree it was prepared for and is skipped once that tree moves, ' +
  'so these decisions were never written to the history (#458)'   // :152-154

That explanation is written for the lost > 0 branch and is emitted for both. When lost === 0 it describes a staging that did not happen and decisions that did not exist.

Why it is worth fixing rather than tolerating

The comment at :102-105 records that #584 fixed the neighbouring version of this — the alarm counted consumed transactions and so was "loudest on the healthy path it exists to distinguish from". This is the same residue one layer along: the count is now right and the sentence explaining it is not.

The practical cost is that a repository with only abandoned drafts is told it silently lost decisions, and commitlore pending ls — the offered fix — shows RECORDS 0 and no way to recover anything, because there is nothing to recover. A reader either distrusts the diagnostic or goes looking for records that never existed.

Suggested shape

Move the explanation inside the lost > 0 branch, and give the other branch its own — an abandoned draft that never staged is a non-event, and saying so plainly is the accurate report. severity may also be worth revisiting for the lost === 0 case, though that is a separate judgement from the wording.

Verified against source at 3843ed0, not the bundle.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions