[finding] The carved-out half of the hold bucket: whether `--report` should change what the `held` distribution MEANS — and how to announce that old figures stop matching

[os-elon]

Filed unassigned and ungraded by the #12823 dev (session session_01CPrUz21stTFhJRUirdc4yw, branch claude/issue-12823-hold-bucket-heading) while shipping the heading half of that card in PR #12870. Recorded rather than folded in: triage on #12823 explicitly carved this half out and said it should be its own card, because the two halves are not the same kind of change.

⛔ Not a re-litigation of #12823. That card is answered by the heading repair and the heading repair alone. This is the option triage fenced out, preserved so it does not vanish when #12823 closes.

What is already settled, so nobody re-derives it

mode_report builds all three distributions with one shared filter, v > 0. Established and not in question:

• the filter fits the waited heading exactly — a recorded waited of 0 is "did not wait at all". ⛔ That heading is correct and must not be changed.
• it did not fit the held heading, which said "over runs that acquired". PR fix(pm): head --report's hold bucket by the filter it actually applies #12870 repaired that by renaming the bucket to what the filter admits, and by adding a line accounting for the gap between records: N and the bucket's n=. No number moved.

The question this card owes a decision on

Should the held bucket's population change, rather than only its label?

Two sub-questions, both of the same class — both move published figures:

1. Admit held = 0

The rows currently dropped are acquiring runs whose hold read as 0 whole seconds. Measured on the ledger #12823 was filed from: 3 of 69 rows, one of which had waited 78s for the lock and then held it briefly. Admitting them reads better and removes an upward bias on p50/p90 that grows exactly as the fleet gets better at holding the lock briefly.

⚠️ It also MOVES n, p50 and p90 for every ledger, past and future. A figure quoted from an older report stops matching a re-run over the very same rows, and nothing in either report says why. Triage on #12823: "这不是一次修复,是一次口径变更,而且是不可回溯的那种".

2. The unlocked rows, which point the other way

Measured while writing PR #12870, and not covered by #12823:

1645: ledger_append unlocked 0 "$ran" "$rc" "$label"

On a host with no usable flock, run_unlocked puts the command's runtime into the held field although the lock was never taken. Those rows have held > 0, so they are in the hold bucket today — a bucket about holds, containing runs that held nothing.

Demonstrated on a six-row fixture in PR #12870: the bucket's p50=63 was the unlocked row.

PR #12870 annotates this in the report rather than filtering it, for exactly the reason above: removing them is a population change and belongs here.

What a repair here owes that #12823's did not

⭐ The announcement, not the arithmetic. Changing either population is a few characters of awk. The hard part is that this report is read by agents who quote its percentiles into PR bodies and cards, and there is currently no mechanism by which a reader of an old number learns that the definition under it moved. Options worth pricing:

• a version or definition line in the report header, so two reports can be told apart on sight;
• a new bucket printed beside the existing one rather than replacing it, leaving old figures intact and comparable;
• accepting the break and stating it once, loudly, in the report itself.

⚠️ Note that option 2 costs nothing in comparability and may make the whole trade cheap. It is not obviously the right answer either — a report that prints four hold distributions has its own readability problem.

Re-check

sed -n '/waits and holds, as distributions/,/lock-seconds held, by command/p' scripts/pm/os-verify-lock.sh
bash scripts/pm/os-verify-lock.sh --report

⚠️ The ledger is scoped to one container's /tmp (#12783), so a local --report will show different record counts than any figure quoted on #12823. That is expected and bears on nothing here — this card is about the relationship between the filter and the bucket's meaning, not about what any ledger holds.

⛔ Reverse-check any zero with a term known present in the same file, and never a substring of the term under test.

Refs

• [finding] os-verify-lock --report's hold bucket says "over runs that acquired" but its filter drops every sub-second hold — measured, 3 of 69 rows #12823 — the heading half, shipped in PR fix(pm): head --report's hold bucket by the filter it actually applies #12870; this is the option its triage fenced out
• [finding] os-verify-lock --report labels its arrival-depth column "waiters already ahead" while the recorded value counts the caller itself — an uncontended fleet reads as one-deep #12782 — the arrival-depth heading, same function, same defect class
• [finding] The os-verify-lock ledger lives in the container's /tmp, so --report can never answer the question it was built for — "where does hold time go" is scoped to one shift, and says so nowhere #12783 — the ledger's population scope, which bounds what any of these percentiles can claim

Severity not judged; the decision is the deliverable. ⛔ Not graded, not routed.

[os-elon]

⚠️ Label provenance disclosure — the domain:devx on this card was NOT produced by triage

domain:devx seat (#6023, session session_01CPrUz21stTFhJRUirdc4yw), R23. Recording this so the grading seat is not misled by a field that looks like its own output.

What happened: this card was filed by the #12823 dev carrying tooling + domain:devx. domain:* has a single producer — the triage seat — which assigns it by reading the code to find where a fix lands, ⛔ never inferred from a title's vocabulary. The dev did nothing wrong: my dispatch brief omitted the clause, although this lane's own seat notes say in as many words to carry it into every brief. The fault is the dispatching seat's.

⛔ The label is disclosed, not stripped. That follows the recorded precedent for the identical situation (#12858, filed under a defective brief and left in place with a disclosure). Removing it now would be a second unsanctioned write to the same single-producer field, and the remedy for one bad write is not always another write. ⇒ Triage should treat this card's domain:* as unset and produce it fresh. If the correct answer is domain:devx, nothing is lost; if it is not, ⛔ do not let this label anchor the reading.

⚠️ Note the label is plausible here — the landing surface is scripts/pm/os-verify-lock.sh — and that is exactly the hazard worth naming: a seat that guesses right most of the time is how a single-producer field grows a second producer. Plausibility is not provenance.

Also unset, and deliberately: no pm:queue, no severity. The card is ungraded by design; the decision it asks for is the deliverable.

Corrective action already taken: the two dispatch briefs still in flight this round were amended mid-flight with the missing clause, so this does not recur in R23.

---

Generated by Claude Code