From 9c633db17ccc3c79dd507a7c0fe7a2ef8c46c7f1 Mon Sep 17 00:00:00 2001 From: wshallwshall Date: Tue, 25 Aug 2026 17:18:25 -0500 Subject: [PATCH] docs(adr)+fix(hooks): the session-mail channel is wired, and four places still called it a prototype (BACKLOG #1215) ADR 0161's status line said the mail-drain code was "a prototype and is deliberately NOT WIRED". It is wired. Measured three ways, each failing differently: source install-coordination.ps1 carries drain rows for SessionStart and Stop -- the same rows the ADR says "stay exactly as they are" installed TWO installed config roots carry mail-drain.ps1, each at BOTH events, so a config root HAS been installed from them observed the drain fired during a real session and reported on that session's own inbox by path The brief named two files. A census found the same false claim in four, one of them shipped code and one a test docstring -- neither reachable from the two the brief named: docs/adr/0161 the status line and the "what gates wiring" section mail-drain.ps1:257 "this channel is deliberately not wired", inside the hook that is wired. Its ARGUMENT survives: the idiom is duplicated because announce-session.ps1 ends in exit 0 and cannot be dot-sourced. Only the reason given was false. test_session_mail.py:5 the module docstring a reader starts from The ADR's false paragraph is CORRECTED IN PLACE rather than deleted. It was true when written, the gating argument still stands, and a reader needs to see what changed. What remains accurate is stated too: wiring was meant to be a separate owner-approved step gated on #1028, and nothing records that approval -- so the open question is not whether it is wired but whether it was wired through the gate the ADR describes. WHAT THIS COMMIT DOES NOT DO, deliberately. It does not move the ADR off `Proposed`. That is a disposition, and an owner's. It does not edit the decision box at the tail into agreement with reality. That box records "DECIDED 2026-08-06: NOT WIRED" for the urgent asyncRewake tier -- and mail-watch.ps1 IS wired at Stop in both installed roots, with a row at install-coordination.ps1:305. So SESSION-MAIL.md's sibling claim, that the tier "is not wired and is not in the installer's wiring table", is false on both halves. Either the decision changed and the record did not, or the tier was wired without it. The contradiction is recorded beside the decision and routed to the owner. A decision that flips as a side effect of a docs fix is indistinguishable in the diff from one that was made. It does not touch SESSION-MAIL.md. That is the operator-facing document, its false claim is about the urgent tier rather than the drain, and correcting it would bake in an answer to the question above. ONE THING WORTH RECORDING FOR THE NEXT READER. A grep for "not wired" also matches test_announce_wiring.py:266 -- which is the MESSAGE of an assert whose condition asserts the drain IS wired. The string is only reachable when the assertion fails, so its presence is evidence the suite checks the opposite of what the grep implies. That test was already correct and was left alone. Verified: 138 passed across test_session_mail.py, test_announce_wiring.py and test_announce_hook.py; ruff clean on the touched test. Co-Authored-By: Claude Opus 5 --- ...sync-session-mail-for-unreachable-peers.md | 34 +++++++++++++++++-- scripts/hooks/mail-drain.ps1 | 4 ++- tests/test_session_mail.py | 7 ++-- 3 files changed, 39 insertions(+), 6 deletions(-) diff --git a/docs/adr/0161-async-session-mail-for-unreachable-peers.md b/docs/adr/0161-async-session-mail-for-unreachable-peers.md index f4326f30c..54822c290 100644 --- a/docs/adr/0161-async-session-mail-for-unreachable-peers.md +++ b/docs/adr/0161-async-session-mail-for-unreachable-peers.md @@ -3,7 +3,10 @@ # ADR 0161 — Async session mail for unreachable peers -- **Status:** Proposed (2026-08-05) — the code is a **prototype and is deliberately NOT WIRED**; see §"Status and what gates wiring" +- **Status:** Proposed (2026-08-05) — **but the code IS WIRED AND LIVE** as of 2026-08-25 (BACKLOG + #1215); the "deliberately not wired" claim this line used to carry was false. Whether the + disposition should move off `Proposed` is an owner call and is deliberately NOT made here. See + §"Status and what gates wiring" - **Date:** 2026-08-05 - **Related:** [BACKLOG #1028](../BACKLOG.md) · [SESSION-MAIL.md](../SESSION-MAIL.md) (the operator-facing document) · [ADR 0158](0158-silent-controls-green-signals-that-mean-nothing-and-shape-over-detection.md) (silent controls — a green signal that means nothing) · [ADR 0160](0160-public-repo-content-policy-operator-and-security-review-material-only.md) (what belongs in the public repo) · [CLAUDE.md](../../CLAUDE.md) §5 (worktrees, git discipline), §9 (PHI), §11 (state a load-bearing fact once; no glyphs) · [PHI.md](../PHI.md) @@ -331,6 +334,25 @@ the realtime channel (D2). ## Status and what gates wiring +> **CORRECTED 2026-08-25 (BACKLOG #1215). THE PARAGRAPH BELOW WAS TRUE WHEN WRITTEN AND IS NOW +> FALSE.** It is kept rather than deleted because the *gating* argument still stands and a reader +> needs to see what changed. **The drain is wired and live.** Measured three ways, each failing +> differently: +> +> 1. **Source.** `scripts/coord/install-coordination.ps1` carries drain rows for `SessionStart` and +> `Stop` — the same rows the paragraph says "stay exactly as they are". +> 2. **Installed state.** TWO installed config roots carry `scripts/hooks/mail-drain.ps1`, each at +> **both** `SessionStart` and `Stop`. So a config root HAS been installed from them. +> 3. **Observed.** The drain fired during a real session on 2026-08-25 and reported on that session's +> own inbox by path. That is the channel running, not a description of it. +> +> The sentence that misleads is *"nothing is live in any session"*. A reader checking whether this +> mechanism can affect them gets a definitive no from an ADR, while the hook is executing on every +> session start and stop. **What remains accurate:** wiring was meant to be a separate, +> owner-approved step gated on [BACKLOG #1028](../BACKLOG.md), and nothing here records that approval +> — so the open question is not whether it is wired but whether it was wired through the gate this +> ADR describes. + This ADR is `Proposed`, and the code it describes is a **prototype that is deliberately not wired**. The rows for the drain hook exist in `scripts/coord/install-coordination.ps1` and stay exactly as they are; no config root has been installed from them, so nothing is live in any session. Wiring is a @@ -396,7 +418,15 @@ Two results, and the second is the one that matters: row pointing at it. The only other occurrence in SESSION-MAIL.md is an internal link back to that section, which is the shape this box asks for rather than a second statement. - [x] Owner decision on whether the urgent `asyncRewake` tier is wired at all, given D11. - **DECIDED 2026-08-06: NOT WIRED, and not rebuilt yet.** The default tier has never delivered + **DECIDED 2026-08-06: NOT WIRED, and not rebuilt yet.** + > **THE SHIPPED STATE CONTRADICTS THIS DECISION (measured 2026-08-25, BACKLOG #1215).** + > `scripts/hooks/mail-watch.ps1` is wired at `Stop` in TWO installed config roots, and + > `install-coordination.ps1:305` carries a row for it (`Marker = $WAKE_MARKER`, `Async = $true`) + > -- so both halves of the sibling claim in [SESSION-MAIL.md](../SESSION-MAIL.md) ("the tier is + > not wired and is not in the installer's wiring table") are false too. **This is a recorded + > owner decision, so it is NOT re-decided here:** either the decision changed and the record did + > not, or the tier was wired without it. Which of those it is, and what the record should say, + > is the owner's to settle. The default tier has never delivered mail in real use -- everything to date is rig-verified and the code is unmerged -- so building a second tier to cut a latency nobody has measured is a demand-gate item, not a gap. The rebuild path is recorded in [SESSION-MAIL.md](../SESSION-MAIL.md) so it is not rediscovered: arm on diff --git a/scripts/hooks/mail-drain.ps1 b/scripts/hooks/mail-drain.ps1 index 2e0023bd5..d7e285a68 100644 --- a/scripts/hooks/mail-drain.ps1 +++ b/scripts/hooks/mail-drain.ps1 @@ -254,7 +254,9 @@ function Get-Clean { # interpolated into a line, and nothing else in this script builds a line from message content. # Same idiom as announce-session.ps1's Get-Clean, with one step added. It is duplicated rather than # shared because announce-session.ps1 is an executable hook that ends in `exit 0` and cannot be - # dot-sourced; extracting it would edit a WIRED hook, and this channel is deliberately not wired. + # dot-sourced; extracting it would edit a WIRED hook. (The original reason added "and this channel + # is deliberately not wired" -- FALSE since BACKLOG #1215: this hook is wired at SessionStart and + # Stop. The duplication argument stands on the dot-sourcing half alone.) # # ORDER IS LOAD-BEARING: # 1. \p{C} -> space. Control characters AND newlines become word breaks, so a field cannot break diff --git a/tests/test_session_mail.py b/tests/test_session_mail.py index 1e95e5361..ed0cdce66 100644 --- a/tests/test_session_mail.py +++ b/tests/test_session_mail.py @@ -2,9 +2,10 @@ # Copyright (C) 2026 MessageFoundry Organization and contributors """Tests for the async session-mail channel (``scripts/coord/mail*.ps1``, ``scripts/hooks/mail-drain.ps1``). -The channel is a PROTOTYPE and is deliberately NOT wired. These tests exist to close the red-team -findings before it ever is, so every one of them drives the REAL script as a subprocess against a -throwaway ``git init`` repo under ``tmp_path``. The live checkout is never touched: sibling sessions +The channel WAS a prototype and is now WIRED -- ``mail-drain.ps1`` runs at ``SessionStart`` and +``Stop`` (BACKLOG #1215; this docstring said "deliberately NOT wired" until then). These tests exist +to close the red-team findings, which they did before wiring, so every one of them drives the REAL +script as a subprocess against a throwaway ``git init`` repo under ``tmp_path``. The live checkout is never touched: sibling sessions are using its mail queue while the suite runs, and the drain mutates state (it claims, moves and receipts) rather than merely reading.