repo-mailbox/docs/2026-08-14-confident-zero-review.md

Design review: where an unknown or an error becomes a confident zero or a successful exit

Date: 2026-08-14. Reviewer: Fable 5/xhigh session (no advisor - Fable cannot carry one). Scope ordered by the operator: ONE lens over four scripts. No fix is implemented here; the operator prioritizes.

Surface examined (the denominator for every "nothing further found" below)

$ wc -l scripts/coord-send.sh scripts/coord-count.sh scripts/board.sh scripts/route.sh
     237 scripts/coord-send.sh
     133 scripts/coord-count.sh
    1083 scripts/board.sh
     329 scripts/route.sh
    1782 total

All 1782 lines were read in full. Every claim below is produced by a command shown with it; each was run against a throwaway mailbox/tree under the session scratchpad (CLAUDE_COORD_DIR / BOARD_ROOTS fixtures), never the real mailbox. NOT examined (out of assignment scope, reported as unmeasured, not clean): coord-inbox.sh, coord-done.sh, coord-sweep.sh, brief-nightly.sh, the four selftests, and both hooks except a single grep of pre-state-line-guard.mjs for finding 13.

Findings, most severe first (reviewer's ranking; operator decides)

1. board.sh: a missing coord-count.sh sibling silently zeroes all debt

board.sh:381, 395, 409, 516-517 all gate on [ -f "$SELFDIR/coord-count.sh" ] and silently skip when it fails; the four invocations also discard stderr. Measured by copying board.sh + route.sh (without coord-count.sh) to a scratch dir, against a fixture mailbox where repo-a holds one reply-owing message:

real board.sh  --brief : "repo-a  INN 1  done" / "1 repo skylder svar"
copied board.sh --brief: "Ingen repo skylder noen et svar i dag."
                         "Disse har bare FYI-post ...: repo-a"   <- mislabel
real   --inbox-plan    : 1 block
copied --inbox-plan    : 0 blocks

Not just absence: the fallback branch actively relabels a reply-owing message as FYI. Dead-letter and orphan cross-checks vanish silently too. A missing sibling is a real deployment state, not hypothetical - the 0.12.1 deployed-copy incident is exactly this shape.

2. coord-send: exit 0 to any well-formed recipient; mailbox created on the spot

(Known instance, re-verified.) coord-send.sh:156-158 validates only the FORM of the name; :176 mkdir -p creates the mailbox.

$ CLAUDE_COORD_DIR=$T bash scripts/coord-send.sh --from testsender \
    --to repo-mailbxo --subject test --message hei
coord-send: delivered to repo-mailbxo (...)   # exit 0, mailbox now exists

A typo'd recipient gets a mailbox no session will ever read, and the sender is told "delivered". The WP1d dead-letter column is the compensating control being designed - but see findings 8 and 11 for two holes in that net.

3. board.sh: a route line outside the vocabulary yields a confident command

(Known instance; the measured mechanism is worse than "parses to 0" - it parses to a VALID value.) route_cmd_for()'s sed captures [a-z-]* (board.sh:481-484), so path=known2 extracts known, which route.sh then legitimately accepts:

STATE.md: <!-- route: path=known2; verification=strong; reversibility=cheap; scope=local; ... -->
--plan  : command=claude --model sonnet --effort high --advisor opus

The function's own comment says "a guessed command reads as authoritative"; the reader violates it while the calculator stays clean. Fully-invalid tokens (path=foo) ARE caught (route.sh dies, command_missing= emitted); it is the prefix/case class that slips through as a confident answer.

4. board.sh: status tokens outside the vocabulary parse to a valid prefix or to "?"

Same [a-z-]* capture at board.sh:285. Fixture measurements:

status=done2   -> table shows "done", sorted into FERDIG; no MALFORMED warning
status=Planned -> "?"; footer says "1 repo mangler board-linje" (it HAS one)

The MALFORMED detector (board.sh:294-298) only ever sees what the regex delivers, so it catches exactly the all-lowercase unknown tokens and nothing else. done2 becomes a confident done; a case typo becomes "missing board line", which is a wrong diagnosis printed as fact.

5. coord-count: missing mailbox root -> exit 0, empty output

coord-count.sh:59 [ -d "$COORD" ] || exit 0.

$ CLAUDE_COORD_DIR=/nonexistent-coord-xyz bash scripts/coord-count.sh; echo $?
0        # no output, no stderr

"Always exit 0" is the SessionStart contract and can stay - but nothing (not even stderr, which interactive callers WOULD see) distinguishes "no mail anywhere" from "the root does not exist". Every board consumer inherits the zero, so one typo'd CLAUDE_COORD_DIR reads as a machine-wide clean slate.

6. board.sh: git failure -> DRT=0 (and the same shape in INN and ALDER)

board.sh:247 git status --porcelain 2>/dev/null | wc -l: any git error (corrupt repo, dubious-ownership refusal) -> empty pipe -> 0. Fixture repo-d with .git as an empty file, an uncommitted STATE.md inside:

repo-a (working git, same content): DRT 1
repo-d (git errors out):            DRT 0

Same mechanism, not separately measured: inbox ls | wc -l at :251-253 (unreadable inbox -> INN 0) and stat failure -> age=0 at :276-277 (ALDER "touched today"). SISTE handles its error case correctly ("-", :260-264) and is the in-file counterexample.

7. coord-send: --to is the only line-oriented field never sanitized

sanitize_field exists for exactly this (coord-send.sh:76-80) and is applied to FROM (:81) and SUBJECT (:141) - denominator: 3 grep hits for sanitize_field, none covering TO. A newline in --to therefore lands verbatim in the to: frontmatter line:

$ ... --to "$(printf 'x\nreply-expected: no')" ...   # exit 0
frontmatter: to: x / reply-expected: no / ... / reply-expected: yes
$ coord-count on that mailbox:
x
reply-expected: no\t1\t0\t0     # two-line record breaks the TSV; owed=0

The injected line silences the debt that the engine itself declared (reply-expected: yes), defeating coord-count's own stated rule that only the frontmatter block may speak - the attack line IS inside the block. Only self-inflicted (the sender already controls --fyi), so robustness rather than security - but a malformed name both corrupts the count format and zeroes an owed reply, with exit 0.

8. coord-send: names in the ..foo class are deliverable but uncountable

Send guards exact ./.. only (:96, :128, :156-158); coord-count's globs "$COORD"/* "$COORD"/.[!.]* (:82) can never match a name starting with ..:

$ ... --to ..foo ...        -> exit 0, delivered
$ ls -a $T                  -> ..foo  repo-mailbxo
$ coord-count               -> repo-mailbxo  1  1  0      # ..foo absent

Mail there is not "never read" - it is never COUNTED, so the dead-letter net (finding 2's compensating control) has a hole for exactly this class.

9. coord-send --reply-to: coord-done failure suppressed, success claimed

coord-send.sh:234 runs coord-done with >/dev/null 2>&1 and then unconditionally prints success. Measured with a stub coord-done.sh (exit 1):

coord-send: original (...) marked handled     # exit 0
$ ls inbox/   -> original still there; no archive/ exists

Self-healing over time (the un-archived original keeps re-injecting), but the printed claim is false at the moment it is made, and a session trusting it will report the reply debt as closed.

10. board.sh: invalid roots -> silence with exit 0

board.sh:235 exits 0 before any rendering when discovery finds nothing:

$ BOARD_ROOTS=/nonexistent-xyz bash scripts/board.sh --plan; echo $?
0        # no output at all

brief-nightly.sh compensates in ITS path (empty render = failure); the interactive table, --plan, --inbox-plan and any driver consuming them get "no repos exist" as a clean success.

11. coord-count: column 4's "-" means three different things

"Has .origin", "no filename matched the timestamp grammar", and "date parse failed" all print the same token (:111-125):

claimedrepo  1 1 -     # has .origin           (fine)
deadrepo     1 1 -     # NO .origin, ungrammatical filename -> unmeasurable
deadrepo2    1 1 13    # the only distinguishable case

The fail-safe direction is documented and right; the collapse is not: a consumer cannot tell "not a dead letter" from "not measured", which is the exact reporting rule this machine's Verifiseringslov exists to enforce. Unmeasured but mechanical: the column rests on BSD-only date -j (:117), so on Linux (this is a public plugin) every mailbox prints "-" forever and WP1d detection is silently inert machine-wide.

12. board.sh:895: the banned NR==FNR idiom survives in the --focus join

$ grep -n 'NR==FNR' scripts/*.sh
board.sh:554,555,831,987   <- four comment lines banning it
board.sh:895               <- one live code site (the --focus keep-join)

Currently safe only through a distant invariant (every resolved slug is declared by >=1 repo, so fp_names is never empty while applied). If any future change lets fp_names be empty, the whole plan silently becomes "0 tabber" - the exact measured 0.21.0 defect this file's comments were written against. The selftest's NR==FNR regression check (board-selftest.sh :1224-1247) covers the OTHER joins only.

13. The MAX_LINES class: operator decisions cast into version-pinned code

(Known instance, confirmed and extended.)

source  pre-state-line-guard.mjs:59          MAX_LINES = 120
cache   .../repo-mailbox/0.23.0/...mjs:57    MAX_LINES = 60
cache   .../repo-mailbox/0.24.0/...mjs:59    MAX_LINES = 120
$ grep -c 'process.env' hooks/scripts/pre-state-line-guard.mjs  -> 0

No env override exists, so a decision reaches enforcement only via release + cache update + per-tab restart (the 60-vs-120 gap was live on this machine between the decision and tonight's update). Same class found in scope: the dead-letter 3-day threshold (board.sh:398) is likewise hard-coded with no override. NESTE_WIDTH=38 is cosmetic and documented as the column's property.

14. Footnote: coord-count's header contract vs. its own code

Header says "Exit: always 0"; --exclude without a value exits 2 (:49). The loud direction is the right one - the header is what needs the correction.

The positive control

route.sh is the in-repo proof that the loud pattern is achievable: every trait is a closed set, every unknown value dies with exit 2, the last-session record is all-or-none, and empty rationale is refused. board.sh's chain-root walk ("credit NOBODY over a guess") is the same discipline. Every finding above is a deviation from a house style the repo itself already defines.

Coverage statement

Within the 1782 lines read: 37 2>/dev/null occurrences (grep -c over the four files) were each judged during the full read; the ones that convert an error into a confident zero/success are findings 1, 5, 6, 9 above, the remainder either fail closed (e.g. coord-send:106 refuses on unreadable sender) or feed paths that label their unknowns. No further instances found within that surface; the unexamined scripts listed at the top are NOT claimed clean.