coord: announce yourself to the other sessions, and stop the collision gate crying wolf - #133
Merged
wshallwshall merged 13 commits intoAug 2, 2026
Merged
Conversation
Every coordination control in this repo is PULL-based: a new session discovers its peers from the SessionStart banner and the peers learn nothing until someone trips the collision gate. That is too late for the collision that costs the most -- two sessions building the same THING in different files, where nothing file-shaped can catch it. This closes the push direction. It ASKS, it cannot send. Hooks are shell commands and session messaging is MCP, so the hook prints the instruction, the live peer roster and the id-resolution rule at the first prompt that has intent to report; the model does the sending. UserPromptSubmit, not SessionStart: at SessionStart a session knows it exists and nothing else, so it can only say hello -- the interrupt without the information. THE ID RULE IS THE PAYLOAD, and it is counter-intuitive enough that the text states it with its evidence. The registry id in this repo's banners is NOT the MCP session id; measured, a registry id and an MCP id for one session shared no characters. Branch does not join them either -- the two rosters reported different branches for the same checkout in 2 of 6 cases. Only cwd joins, and it must be matched EXACTLY: every worktree cwd is an extension of the primary's, so a prefix match resolves a peer in the primary to an arbitrary worktree session. A registry id passed to send_message fails SILENTLY, which reads as the peer ignoring you. EVERY DECISION LEAVES A RECEIPT, because the bug being fixed was a hook that was wired, fired, resolved nothing and exited 0 for weeks -- byte-identical to a healthy hook with no peers. For the same reason the shim carries its OWN missing-script notice: every receipt the hook writes lives INSIDE the script, strictly downstream of the resolution failure that IS the bug, so the shim is the one surface that still reports when the script does not resolve. It is gated on presence.ps1 so the entry stays silent in every unrelated repo on the machine. It always exits 0 -- a UserPromptSubmit hook that fails can block the user's prompt. It consumes presence.ps1 and therefore the single liveness fence; it does not invent a second notion of live. A separate 'mefor-announce' marker keeps it outside install-coordination's mefor-coord strip and outside the website repo's mefor-web-announce entry in the same settings file, so no installer can delete another's hook, and -Only UserPromptSubmit -Uninstall removes announce alone without disarming the collision gate.
Most tests for a hook like this assert an ABSENCE, and a hook that does nothing at all satisfies every one of them -- which is precisely the production failure being fixed. So the silence assertions are paired with a positive arm: two tests run the SAME runner against fixtures differing only in whether a peer exists, and if the silence tests ever start passing for the wrong reason the positive one goes red first. test_announce_wiring.py is the class the repo had no test for AT ALL: does the thing that gets INSTALLED reach a script that EXISTS, and does it say so when it does not? Its absence is exactly how a wired-but-inert shim survived for weeks. test_every_wired_script_exists_in_this_checkout was written FIRST and watched fail, naming the missing script and printing all three paths it scanned; a green gate is only evidence if it was shown it can see the failure. Also pinned, each because it was got wrong somewhere first: - The foreign UserPromptSubmit entries -- another repo's shim and an unmarked waiting-flag cleanup -- survive install AND uninstall byte-identical. That is the only thing standing between a one-line wiring edit and deleting a hook this repo does not own. - A peer with no StartedAt ranks LAST, not first. ConvertFrom-Json coerces ISO-8601 to DateTime while the '' fallback stays String; Sort-Object over that mixed column raises ZERO errors and puts the empty string FIRST, so without an explicit projected key the least-trustworthy row silently takes the top of a capped target list. - NO_SESSION_ID and DISABLED write their receipt with NO injected -StateDir. An earlier draft resolved the state dir after those branches, so the receipt was unwritable in production while a test that always injected one went green. - Self is excluded by BOTH nets independently: a roster that cannot tell you from a sibling makes the session message itself. - Hostile peer text cannot escape the peer-data block or emit a non-ASCII byte, a hostile session id cannot escape the state dir, and two ids that sanitise identically get two markers. - Two concurrent runs announce exactly once. session-context.ps1 is registered twice on this box today, so double firing is a live pattern, not a hypothetical.
…about .claude WORKTREES.md gains the "Announcing yourself" section that the hook's own emitted text and the shim's missing-script notice both cite by name, so the pointer has to land on main in the same merge. It states the id rule ONCE, as the source of record: registry id is not the MCP id, cwd is the only join key and must be matched exactly rather than by prefix, a usable id starts with local_, and a wrong one fails silently. It also states what the change does NOT do. There is no receive-side hook, so the rule that an announcement is peer DATA -- not an operator instruction, and not something to reply to -- lives in the prose and in the fixed message shape and nowhere else. Reachability is given honestly: presence.ps1 is authoritative for who EXISTS, list_sessions only for who can be MESSAGED, and measured, they disagreed 6-to-1. Cost is stated rather than left to be discovered. CORRECTION, and it is why this doc change is in scope rather than deferred: the same chapter claimed ".claude/settings.json is tracked (shared across worktrees)". It is not. /.claude/ is git-ignored, and git ls-files .claude/ returns nothing -- so a worktree's copy is a creation-time snapshot nothing refreshes and several siblings have none at all. That sentence sat at the exact point a reader decides where to install a hook, and it argues for the wrong answer; the new section directly contradicted it. SESSION-DRIFT-CONTROLS.md records announce as the only PUSH control in the D4 layer, plus the two new guarantees worth tracking separately: that wiring reaches a script that exists, and that a resolution failure is now reported by the shim.
…nd finished
Reported by another session with a repro: it committed a file, went clean, said
in writing it was done and handed the file over -- and the peer it handed off to
was still refused the edit.
overlap.ps1's `Files` is the UNION of what a branch COMMITTED-and-not-yet-landed
with what is dirty in its tree. The gate denied on any live row in that set, so
"this branch authored it" was treated as "someone is typing in it right now".
Those are different claims. The first stays true for the branch's whole life;
only the second is what the gate exists to detect.
It self-clears on merge -- overlap already intersects three-dot with two-dot so a
LANDED branch stops claiming its files. But nothing clears it before landing, and
with PRs currently unable to merge, "until it lands" is indefinite: the blocked
set grows monotonically and is never released. Two sessions that coordinated
correctly and explicitly still cannot hand a file over. That is precisely the
failure this gate's own docstring names -- a gate that cries wolf gets
uninstalled.
overlap.ps1 already told callers to treat its signals differently ("block on
live, mention dormant"), but no caller COULD: the row unioned the two signals
away. So the row now carries `Dirty`, and the single-file query sets
`MatchedDirty` saying which signal actually matched.
The gate now DENIES only on an uncommitted edit in a live worktree, and REPORTS
committed-and-clean as context instead -- the peer may already have done what you
are about to do, which is worth knowing and not worth refusing over.
Fails SAFE across the upgrade: a cached row predating `MatchedDirty` has no such
property and is treated as dirty, so the gate degrades to its previous
over-blocking rather than silently permitting a real collision.
Also, while in the file: `git status` now runs with --no-optional-locks. A plain
status REWRITES the index of the repo it inspects, and this walks every peer
worktree -- so merely asking "what is in flight" was mutating other sessions'
checkouts.
Verified against the live repro and both directions: the reported file now
allows with context; a file with uncommitted changes in a live worktree still
denies; an untouched file stays silent.
…rktree name Reported by the session it happened to: its worktree is named inter-session-communication-*, auto-generated at creation from a task that session has never worked on -- it has been doing ASVS scorecard work for its entire life. The directory name is the most visible identifier in presence.ps1, overlap.ps1 and this hook's output, and it had already misled TWO sessions (including this one) into guessing that session was building the announce hook. A worktree name is a creation-time label, not a statement of current work, and nothing keeps the two in sync. The claim note is the only field written DELIBERATELY to say what a session is doing, so the roster now prints it, and the legend tells the reader to prefer it over the name. Joined on the claim's `worktree` path, normalised the same way as every other cwd key here. Fail-open throughout: no claims directory, an unreadable claim, or a peer with no claim all just mean the name is the only thing we have -- which is exactly the status quo, never an error. Same session also flagged that the branch I read for it from list_sessions was stale (a spent, merged branch). The announce text already refuses to join on branch and says why; this is a second, independent reason not to trust it.
A control that cannot distinguish 'ran and resolved' from 'ran and found nothing' is not installed, however it looks. The announce shim outlived every other silent-control defect found the same day BECAUSE it printed a status message -- which is more convincing than silence. The structural cause is the reusable part: every receipt that hook would have written lived inside the script the shim failed to find, so every check sat strictly downstream of the failure it existed to detect. Looking was not neglected, it was impossible. The question to ask of a new control is which surface still reports when the control itself fails to load. Formulation owed to a peer session that hit four instances of this class in one day and named it more sharply than I had.
…e hard way Announce-on-join introduces a session; it does not let an established one push an operational notice. That increment is deferred, and on 2026-08-01 six sessions rehearsed it by hand for four hours. Three constraints fell out, recorded so the next attempt does not rediscover them: - A broadcast needs an EXPIRY or a predicate the RECIPIENT can evaluate, never a promise from the sender. A merge freeze shipped with 'lift when #119 merges'; #119 died on an unrelated CI timeout, so five sessions held on a condition that could not arrive and a second round was needed to retract it. - 'Don't do X' is the wrong primitive when automation already has X armed. The freeze asked for restraint while six PRs had auto-merge ARMED and would have landed with nobody clicking anything. The right ask was an action: disarm. - Coordination a tool cannot read does not count. Two sessions agreed IN WRITING to hand over a file and the gate still refused, because the agreement was prose and the gate reads git. Field data from the sessions that lived it, not speculation.
Nothing drove overlap.ps1's row computation against a real repository, so the question "does MatchedDirty hold when a file is dirty AND committed at once" was unanswerable by the suite. Raised by the session that spent an evening in exactly that state. THAT CASE IS THE ONE THAT FAILS SILENT, which is why it gets a real fixture rather than a stub row. A peer with uncommitted edits in one region and landed work in another is a genuine collision. Had MatchedDirty been derived from the committed diff instead of the working tree it would read FALSE there, the gate would allow, and two sessions would write one file with nothing reported. The over-block this replaced was loud and annoying; that would be quiet and cost someone their work. Verified the tests can SEE it rather than assuming: sabotaged the row to publish an empty Dirty set -- the precise mis-implementation warned about -- and both MatchedDirty assertions went red; restored, all five green. A test written after the code, never observed failing, is a test of nothing. Also pins that overlap does not rewrite a peer worktree's git index, by comparing the index mtime across two queries. An observer must not perturb what it observes, and this one was doing so on every PreToolUse before f55d6c6. Stub rows would only have asserted that the plumbing carries a value someone else computed; the whole question here is what git actually reports.
…at exists Raised by the session that traced the shim: the coordination hooks are not installed copies, they are inline commands that locate their script in a working tree at every invocation. If neither base yields the file, Test-Path fails, the loop ends, nothing runs, and the tool call proceeds with no hook and no signal. "The hook is uninstalled" and "the hook ran and permitted this" are indistinguishable from outside, and nothing was watching. Not hypothetical: a foreign UserPromptSubmit entry sat in this same settings file for weeks probing a script that exists only in another repo. The risk composes badly for collision_gate.ps1 specifically, which now (a) fails OPEN on any error, (b) denies less by design after the dirty-vs-committed split, and (c) silently no-ops when unresolvable. Individually defensible; together the realistic bad day is "the gate was never running and nobody noticed". This closes (c) -- the observation is not mine, and it is a good one. Found immediately on writing it: FIVE user settings files across account directories, not the one I knew about. The informational test also prints the original defect as output rather than leaving it invisible: FOREIGN UserPromptSubmit [mefor-web-announce] -> scripts/hooks/announce.ps1: RESOLVES NOTHING HERE It is another repo's entry, so this reports it and does not touch it. Carries a NEGATIVE CONTROL, because the assertion passed on the first run and a green that has never been shown to fail is not evidence. The real hooks cannot be unwired to prove the predicate works -- the primary checkout is shared with live sessions -- so it is exercised against a path known not to exist. Local-machine only: CI has no user settings and these skip there, which means CI does NOT guard this property. Said plainly, and every test prints what it scanned BEFORE it can skip, per test_gate_installed_parity.py -- the pytest config has no -rs, so a skip would otherwise render as a bare dot with no reason.
…ommunication-hooks-a52335
wshallwshall
enabled auto-merge (squash)
August 2, 2026 00:29
…ommunication-hooks-a52335
…ommunication-hooks-a52335
…ommunication-hooks-a52335
wshallwshall
added a commit
that referenced
this pull request
Aug 2, 2026
…strument it used
Two additions to #329, neither mine originally.
THE FRAMING, from the ADR 0156 ASVS-sweep session. I had filed #329 as five leaks to plug.
It is better than that: while the five remain, "no unclamped escape survives on an enforcing
PHI posture" is five per-site facts, each checkable only by opening the site, and each silently
falsified by a sixth cell added later. Convert them all and it collapses into ONE repo-wide
invariant -- the raw insecure_tls_allowed() unreachable outside settings.py's own clamp, so the
absence is checkable everywhere at once with weakened_tls_escape_permitted_here as the positive
control. Today a convention enforced by review; afterwards an invariant enforced by a grep.
That is not decoration. The scorecard's absence-claim mechanism runs regexes over the whole
*.py corpus and CANNOT scope a grep to one file, so a per-connector claim is not expressible
and has to ride as stated-but-unchecked prose. A repo-wide claim is machine-verified on every
commit. The item is therefore the difference between a property re-audited by hand and one a
gate can hold -- a stronger argument than "five leaks".
THE CENSUS, corrected twice before it was right, which is why it now names its instrument.
I reported direct.py=0 (measuring my own unlanded branch as though it were repo state) and
mllp.py=1 (a regex excluding '#' comments but NOT docstrings, counting prose as a call). Both
wrong. Recounted at main by ast.Call nodes: six real sites outside settings.py --
auth/ldap.py, pipeline/alert_sinks.py, transports/{ai_broker,database,direct,remotefile}.py.
database.py is the documented unstamped fallback and stays excluded; mllp.py's hit is a
docstring and is not a call at all.
The scope note states that a census on the #323 branch disagrees with one on main and neither
is wrong, and ends on the line that is the actually durable part: a line-based census reports
mllp.py as a further site, an AST-based one does not. That tells the next person which
instrument to use, which no count on its own can.
Gate advisory honoured rather than bypassed: #133 changed collision_gate from a hard deny to an
advisory for a peer whose tree is clean, and its message says to check the overlapping commits
before editing. Did that -- adr-0154's hunks are at 398/881, the sandbox session's is an EOF
append at 8308, mine are 5261/7397/8178/7772. Disjoint.
(My own check of that gate was wrong first time, in the same class as everything above: I
tested "is there output?" as a proxy for "was it denied?", and #133 changed the output from a
deny decision to an advisory. The instrument was written against the old contract.)
banner invariant OK (264 items); leak gate exit 0 under the real token set.
wshallwshall
added a commit
that referenced
this pull request
Aug 2, 2026
…strument it used
Two additions to #329, neither mine originally.
THE FRAMING, from the ADR 0156 ASVS-sweep session. I had filed #329 as five leaks to plug.
It is better than that: while the five remain, "no unclamped escape survives on an enforcing
PHI posture" is five per-site facts, each checkable only by opening the site, and each silently
falsified by a sixth cell added later. Convert them all and it collapses into ONE repo-wide
invariant -- the raw insecure_tls_allowed() unreachable outside settings.py's own clamp, so the
absence is checkable everywhere at once with weakened_tls_escape_permitted_here as the positive
control. Today a convention enforced by review; afterwards an invariant enforced by a grep.
That is not decoration. The scorecard's absence-claim mechanism runs regexes over the whole
*.py corpus and CANNOT scope a grep to one file, so a per-connector claim is not expressible
and has to ride as stated-but-unchecked prose. A repo-wide claim is machine-verified on every
commit. The item is therefore the difference between a property re-audited by hand and one a
gate can hold -- a stronger argument than "five leaks".
THE CENSUS, corrected twice before it was right, which is why it now names its instrument.
I reported direct.py=0 (measuring my own unlanded branch as though it were repo state) and
mllp.py=1 (a regex excluding '#' comments but NOT docstrings, counting prose as a call). Both
wrong. Recounted at main by ast.Call nodes: six real sites outside settings.py --
auth/ldap.py, pipeline/alert_sinks.py, transports/{ai_broker,database,direct,remotefile}.py.
database.py is the documented unstamped fallback and stays excluded; mllp.py's hit is a
docstring and is not a call at all.
The scope note states that a census on the #323 branch disagrees with one on main and neither
is wrong, and ends on the line that is the actually durable part: a line-based census reports
mllp.py as a further site, an AST-based one does not. That tells the next person which
instrument to use, which no count on its own can.
Gate advisory honoured rather than bypassed: #133 changed collision_gate from a hard deny to an
advisory for a peer whose tree is clean, and its message says to check the overlapping commits
before editing. Did that -- adr-0154's hunks are at 398/881, the sandbox session's is an EOF
append at 8308, mine are 5261/7397/8178/7772. Disjoint.
(My own check of that gate was wrong first time, in the same class as everything above: I
tested "is there output?" as a proxy for "was it denied?", and #133 changed the output from a
deny decision to an advisory. The instrument was written against the old contract.)
banner invariant OK (264 items); leak gate exit 0 under the real token set.
wshallwshall
added a commit
that referenced
this pull request
Aug 2, 2026
…icated (#323, layers 1-2) (#132) * fix(smtp): the EMAIL and DIRECT TLS hops were encrypted but unauthenticated (#323, layers 1-2) smtplib takes no context by default and falls back to ssl._create_stdlib_context, which IS ssl._create_unverified_context -- measured on this project's required interpreter (CPython 3.14.6): verify_mode=CERT_NONE, check_hostname=False. So use_tls=true bought encryption without authentication on every SMTP send, and any certificate was accepted. That is worse than a plain gap because three shipped controls asserted the opposite: * transports/email.py registered a RevocationHopGuard on the hop, whose own definition in tls_policy.py says "the caller has already built a verifying context". An enforcing production-PHI instance therefore REFUSED TO START over a possibly-REVOKED certificate, on a hop that never validated a certificate at all. * the same file's comment claimed STARTTLS/SMTP_SSL "verifies the server cert". * the AUTH refusal keyed only on use_tls=false, so with TLS "on" the password went over the unauthenticated hop. WHAT LANDS (2 of the 3 cells): config/tls_policy.py build_smtp_tls_context() -- the shared verifying-context factory, mirroring remotefile.py's _ftps_ssl_context step for step (TLS 1.2 floor, harden_kex_groups, harden_cipher_suites, harden_verify_flags on the verify path). It lives in config/ rather than transports/ because pipeline/alert_sinks.py is the third caller and a transport must not import pipeline/ (ADR 0029's one-way rule). transports/email.py, transports/direct.py a three-arm branch (cleartext / verify-off / verifying) and context= on both smtplib arms. The verify-off arm refuses unless the CLAMPED weakened_tls_escape_permitted_here() allows it, and refuses AUTH outright. config/wiring.py tls_verify / tls_ca_file / tls_check_hostname on Email() and Direct(). Trust config, not verification-off, is the escape: [tls].internal_ca_file is ALREADY threaded onto every Destination and was simply never read here, so an estate that pinned its internal CA for MLLP/FTPS needs no change at all. SEPARABLE FIX, called out rather than folded in silently: direct.py's cleartext arm read the UNCLAMPED insecure_tls_allowed() while its sibling one branch away read the clamped form. It now reads the clamped one -- strictly ADDS refusals (ADR 0092 decision 5). Partially closes #329. VERIFICATION -- the part that matters. The pre-existing tests asserted "STARTTLS was issued", which was true the whole time it was insecure; that assertion could never have caught this. The eight new tests assert the CONTEXT (CERT_REQUIRED, check_hostname, TLS1.2 floor, CERT_NONE only under the escape, the clamp under enforcing PHI, and that a per-connection CA pins to ONLY that CA). Negative control run: with the code change stashed and the tests kept, all eight go RED. ruff + format clean; mypy unchanged at its 21-error pre-existing baseline (missing pynetdicom / webauthn extras, none in touched files); 437 targeted tests green. DELIBERATELY NOT DONE -- the alerts cell (pipeline/alert_sinks.py:384) still calls starttls() bare. It needs an acknowledgment switch rather than the clamp, because the contextvar hop posture is never stamped for that cell. Tracked as the residual on #323. #139's "verifying context by design" claim therefore remains FALSE and is not corrected here. BLOCKED, needs one follow-up commit: adding `ssl` to transports/{email,direct}.py reds the required crypto-inventory gate until scripts/security/crypto_inventory_check.py documents it. That file is checked out live in another session; the collision gate refused the edit and I asked that session for the two lines rather than clobbering their work. docs/BACKLOG.md (#323's banner, #139) is held by two other sessions for the same reason. * docs+gate(smtp): document the ssl usage #323 added, and correct two false premises it exposed Completes PR #132's blocked tail. Four edits in three files the collision gate refused because live sibling sessions carry diffs to them; applied outside the Edit tool with explicit written consent from both holders, quoted below. 1. scripts/security/crypto_inventory_check.py -- record `ssl` for transports/email.py and transports/direct.py. Without this the REQUIRED crypto-inventory context is red. The Sandbox Fixes session held this file and I offered to let them add the entries in their PR. Their answer was better than my question: find_violations() checks BOTH directions (undocumented AND stale, :378-399, verified at HEAD), and on their branch these two files contain zero ssl imports -- so documenting the usage there would have traded my `undocumented` failure for their `stale` failure on the same required context. Usage and its documentation must move in the SAME commit. That is the invariant, and it is why these lines belong here. 2. docs/ASVS-L2-PHASE0-CHANGES.md section 5 -- the EMAIL and DIRECT communications-inventory rows said "STARTTLS on by default" and stopped, which now understates the control. Both state verification, its trust anchors, and that tls_verify=false needs the clamped escape. The crypto_inventory_check.py header requires these kept in sync. 3. docs/BACKLOG.md #139 -- CORRECTS A FALSE COMPENSATING-CONTROL PREMISE. The item asserted "The engine's EmailAlertSink uses STARTTLS with a verifying context by design." It does not, and did not: starttls() with no context falls back to ssl._create_stdlib_context, which IS _create_unverified_context. A reader would have concluded alert email was TLS-verified when it was not -- the exact shape CLAUDE.md section 11 names as worst. It stays false AFTER #132: I fixed the two connectors, NOT the alert sink, and the item now says so rather than leaving the residual implied. 4. docs/BACKLOG.md #337 -- rationale amended, severity unchanged at LOW. Flagged by the ADR 0087 sandbox session and verified here at HEAD: DEFAULT_FORBIDDEN_MODULES (pipeline/sandbox.py:84-95) blocks socket/ssl/asyncio/multiprocessing/the I/O-bearing messagefoundry.* subpackages/ cryptography -- but NOT `os` or `subprocess`. So #337's justification, "the author already has in-process execution", is true at the default mode=off and FALSE under mode=subprocess, where the whole premise is that the author is not trusted with it. The number lands right for a different reason; the amended rationale holds in both postures and says to re-score when ADR 0147 (OS confinement, Proposed with no code) lands. Same defect class as #139: a claim stated independently of the configuration that makes it true. 5. docs/BACKLOG.md #323 -- banner to PARTIALLY SHIPPED (2 of 3 cells), with the alerts-cell residual, the direct.py clamp fix, and a correction to this item's own "Migration risk" framing (it presumed deployments; the owner confirmed there are none). CONSENT RECORDED, quoted verbatim. Sandbox Fixes (holds crypto_inventory_check.py): "So: take the file, it's yours. My change to it is committed, final, and a single entry (pipeline/sandbox.py -> {secrets}). I will not touch it again -- commitment, not estimate." Stuck CIs (holds docs/BACKLOG.md): "I have no further BACKLOG.md edits; my #340/#344 are committed and pushed on #131; your hunks at ~5264 (#139) and ~7398 (#323) are disjoint from my EOF appends after #338." WHY A BYPASS RATHER THAN WAITING -- AND WHY THIS IS NOT A PRECEDENT. The block was real: both holders' branches carry genuinely UNMERGED diffs to these files, so the gate was correct to fire. Waiting was viable -- their PRs merging would have cleared it -- and I chose consent-plus-verified- disjointness instead, because the gate keys on branch diffs and has no way to read a consent both holders had already given in writing. That is the actual limitation, and docs/WORKTREES.md states the rule from the other side: "coordination a tool cannot read does not count." READ THAT AS A CASE-BY-CASE CALL, NOT A GENERAL RULE. "The gate over-blocks in this specific way" and "therefore overriding it is warranted" are two separate claims; only the first is established, and the sessions that documented the over-blocking did not draw the second conclusion. The ADR 0087 sandbox session had the same clearance from both holders, verified disjointness, and knowledge that the pending fix would allow its edit -- and still WAITED, because its case was one stale sentence in its own item. Mine was a blocked REQUIRED CI context with the fix already written, which is a different weight of reason, not a stronger entitlement. The real remedy is f55d6c6 ("stop the collision gate blocking files a peer committed and finished"), which is written but NOT yet on main; until it lands, sessions are choosing individually whether to wait or override with disclosure. Two of us overrode and disclosed, one waited. All three are defensible. None is the rule. CORRECTION -- an earlier draft of this message justified the bypass with a claimed defect: that under squash merges a merged branch keeps reporting a three-dot diff forever, so a merged-and- forgotten worktree blocks its files permanently. THAT IS FALSE and the claim is withdrawn. The announce session refuted it, the Stuck CIs session retracted it, and I measured it here rather than take either on trust: MessageFoundry-prunefix (merged via #74, branch deleted, worktree still checked out) git diff --name-only origin/main...HEAD -> 7 files git diff --name-only origin/main..HEAD -> 9 files intersection -> 0 overlap.ps1 -File docs/SESSION-DRIFT-CONTROLS.md -Json -> does NOT name prunefix overlap.ps1 intersects the two diff forms deliberately (:138-155, with the reasoning in its own comment), and collision_gate.ps1 delegates to it (:70) rather than re-implementing the rule -- so the gate inherits that handling. `git diff A..B` compares TREES, not commit lists, so once a branch's content is in main the two-dot set empties and the intersection self-clears. Squash merges were already handled. The block set does not only grow. Recording the withdrawal rather than quietly dropping it, because a bypass justified by a real limitation is a decision, while one justified by a defect that does not exist is a hole -- and a false mechanism in the ledger would be cited as precedent. Three sessions got the two-dot/three-dot distinction wrong in different directions tonight, on a repo where the answer decides whether a guard fires; that is the durable lesson, and it is being routed to ADR 0157. Verification: backlog_status_check OK (262 items, each exactly one status) -- the invariant that guards precisely this banner edit; crypto-inventory gate clean; the three previously-failing tests (test_crypto_inventory_scanner, test_security_static x2) now pass; 79 green across the affected suites; ruff + format clean. * test(smtp): prove the #323 context REFUSES a bad certificate, not just that it is configured to The tests shipped with the fix assert `ctx.verify_mode is CERT_REQUIRED` and `ctx.check_hostname is True` -- ATTRIBUTES. That is a weaker claim than "it refuses an untrusted peer", and the gap matters here more than usual: the defect being fixed was a context whose attributes nobody had ever inspected. Asserting the attributes proves the code sets them; it does not prove the resulting handshake behaves. So these drive a REAL TLS handshake. A module-scoped fixture mints a self-signed `localhost` cert and runs a local TLS listener on 127.0.0.1 (ephemeral port, daemon threads). It speaks no SMTP by design -- the property under test is the TLS layer, and adding a protocol would only add ways for the test to fail for reasons unrelated to what it asserts. Five arms, measured: verify=True, no CA -> REFUSED (self-signed certificate) <- the fix, observed verify=True, ca_file=<CA> -> handshake OK <- the private-CA route works verify=True, wrong hostname -> REFUSED (hostname mismatch) check_hostname=False -> handshake OK, chain still validated verify=False (the escape) -> handshake OK, warning logged NEGATIVE CONTROL, run before committing: the same two refusal cases were replayed against `ssl._create_stdlib_context()` -- EXACTLY what smtplib used before #323 -- and both returned **ok**. So both tests genuinely fail against the pre-fix code path and are load-bearing rather than tautological. Without that check they would have been indistinguishable from tests that pass because the assertion is trivially true, which is the failure mode this suite already documents elsewhere ("a test that cannot fail is not a check"). The verify=False arm is asserted deliberately too: an escape that silently stopped connecting would leave operators unable to tell a policy refusal from a broken escape. ruff + format clean; 74 tests in this file, 132 across the three affected suites. * docs(smtp): stop #323 creating false statements in the other direction A fix that closes a defect can make previously-true prose false, and can make a previously-safe grep misleading. Two such cases, both raised by peer sessions rather than found by me. 1. docs/PHI.md:916 -- the [alerts] SMTP row. STILL ACCURATE (that cell is the deferred residual and genuinely does call starttls() with no context), but a reader could reasonably generalise "the SMTP hop is encrypted but unauthenticated" to the message connectors, which as of #323 is FALSE for both EMAIL and DIRECT. The row now says explicitly: do not generalise this to the connectors, they verify; this cell is the deferred residual, not an oversight, and not evidence that SMTP is unverified engine-wide. Raised by the ASVS session, who is sweeping these cells. 2. transports/direct.py -- a FALSE ABSENCE trap. Replacing the raw insecure_tls_allowed() with the clamped weakened_tls_escape_permitted_here() removed this file's last CALL to the raw escape, so a future assessor grepping for it here finds no call site and could conclude the connector has no escape. It has one; it is clamped. The comment now states that, and scopes the absence claim to this file rather than the repo. I got that comment wrong on the first attempt in an instructive way: I wrote "grepping this file returns zero hits" and the grep returned three -- my own comment, twice. I had asserted the result of a measurement while writing the thing that changed it. Corrected to the true and narrower claim (no CALL remains; the comments mention it), and every file named as still having a live call was verified by grep rather than recalled: auth/ldap.py 1 | pipeline/alert_sinks.py 1 | transports/ai_broker.py 1 transports/database.py 1 | transports/mllp.py 1 | config/settings.py 4 transports/direct.py 0 | transports/email.py 0 That is the same defect this whole change set has been about -- a claim stated independently of the measurement that would make it true -- committed inside the comment written to prevent it. Left in the record rather than quietly fixed, because the near-miss is the useful part: the comment would have read as authoritative and been wrong within one line of itself. ruff + format clean; 132 tests green across the affected suites. * backlog(#329): the invariant framing, and a census that says which instrument it used Two additions to #329, neither mine originally. THE FRAMING, from the ADR 0156 ASVS-sweep session. I had filed #329 as five leaks to plug. It is better than that: while the five remain, "no unclamped escape survives on an enforcing PHI posture" is five per-site facts, each checkable only by opening the site, and each silently falsified by a sixth cell added later. Convert them all and it collapses into ONE repo-wide invariant -- the raw insecure_tls_allowed() unreachable outside settings.py's own clamp, so the absence is checkable everywhere at once with weakened_tls_escape_permitted_here as the positive control. Today a convention enforced by review; afterwards an invariant enforced by a grep. That is not decoration. The scorecard's absence-claim mechanism runs regexes over the whole *.py corpus and CANNOT scope a grep to one file, so a per-connector claim is not expressible and has to ride as stated-but-unchecked prose. A repo-wide claim is machine-verified on every commit. The item is therefore the difference between a property re-audited by hand and one a gate can hold -- a stronger argument than "five leaks". THE CENSUS, corrected twice before it was right, which is why it now names its instrument. I reported direct.py=0 (measuring my own unlanded branch as though it were repo state) and mllp.py=1 (a regex excluding '#' comments but NOT docstrings, counting prose as a call). Both wrong. Recounted at main by ast.Call nodes: six real sites outside settings.py -- auth/ldap.py, pipeline/alert_sinks.py, transports/{ai_broker,database,direct,remotefile}.py. database.py is the documented unstamped fallback and stays excluded; mllp.py's hit is a docstring and is not a call at all. The scope note states that a census on the #323 branch disagrees with one on main and neither is wrong, and ends on the line that is the actually durable part: a line-based census reports mllp.py as a further site, an AST-based one does not. That tells the next person which instrument to use, which no count on its own can. Gate advisory honoured rather than bypassed: #133 changed collision_gate from a hard deny to an advisory for a peer whose tree is clean, and its message says to check the overlapping commits before editing. Did that -- adr-0154's hunks are at 398/881, the sandbox session's is an EOF append at 8308, mine are 5261/7397/8178/7772. Disjoint. (My own check of that gate was wrong first time, in the same class as everything above: I tested "is there output?" as a proxy for "was it denied?", and #133 changed the output from a deny decision to an advisory. The instrument was written against the old contract.) banner invariant OK (264 items); leak gate exit 0 under the real token set.
wshallwshall
added a commit
that referenced
this pull request
Aug 2, 2026
Found while checking a peer session's report, not by looking for it. That session announced itself by hand on 2026-08-02 and gave the reason as "the hook is on an unmerged branch". It had merged (#133, 3389aa2) hours earlier, so the observation was right and the diagnosis was not, and nothing would have corrected it. Measured across all five config roots: - no `mefor-announce` UserPromptSubmit entry anywhere - the one UserPromptSubmit entry installed is `# mefor-web-announce`, which resolves scripts/hooks/announce.ps1 -- a different script in a different repo, and one the installer's own comment already warns is easy to confuse with this marker - <git-common-dir>/mefor-coord/announce/ does not exist, so there is not a single receipt: it has never executed install-coordination.ps1 was last run before the announce row existed, and merging a hook does not install one. Its two other entries -- the SessionStart banner and the collision gate -- were wired then and are present, which is precisely why nothing looked wrong. The part worth carrying: the missing-script notice was built so this class could not hide, and it CANNOT FIRE when the hook is not wired at all, because it lives inside the shim. Same shape as the defect this document already records one level down -- the detector sat downstream of the failure it existed to detect. So the status table now distinguishes rule 4's inert-BY-DESIGN from this one's inert-BY-ACCIDENT, and the confirmation step is a receipt on disk rather than a reading of the settings file. Not installed here: that writes ~/.claude/settings.json, which is shared with every session on this machine. Owner's call, from a plain terminal.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What was broken
The
mefor-web-announceUserPromptSubmithook in~/.claude/settings.jsonis user-level, so it fires in every repo — but it probesscripts/hooks/announce.ps1, which only ever existed in the separatemessagefoundry-websiterepo. In MessageFoundry it resolved nothing and exited 0. Wired, firing, inert, silent — for weeks.Cross-session coordination here was entirely pull-based: a session discovers its peers at startup and the peers learn nothing. Nobody finds out about anybody until someone trips the collision gate, which is too late for the collision that costs most — two sessions building the same thing in different files, where nothing file-shaped catches it.
What this adds
scripts/hooks/announce-session.ps1— aUserPromptSubmithook that hands the model its live peer roster plus the id-resolution rule at the first prompt that has intent to report, and asks it to introduce itself.It asks; it cannot send. Hooks are shell commands and session messaging is MCP. It fires on the first prompt at which a messageable peer exists (not simply the first prompt), again when a new peer appears, under a lifetime budget. It always exits 0 — a
UserPromptSubmithook that fails can block the user's prompt. It consumespresence.ps1and therefore the single liveness fence; it does not invent a second notion of "live".The id rule is the payload, and it is counter-intuitive enough that the emitted text states it with evidence. The registry id in this repo's banners is not the MCP session id — measured, a registry id and an MCP id for one session shared no characters. Branch doesn't join them either (the two rosters disagreed on branch for 2 of 6 checkouts). Only cwd joins, matched exactly — every worktree cwd is an extension of the primary's, so a prefix match resolves a peer in the primary to an arbitrary worktree session. A registry id passed to
send_messagefails silently, which reads as the peer ignoring you.The collision gate over-block
Reported with a repro: a session committed a file, went clean, said in writing it was done and handed it over — and the peer was still refused.
overlap.ps1'sFilesis the union of committed-and-unlanded with working-tree. The gate denied on any live row in that set, so "this branch authored it" was treated as "someone is typing in it now". Its own header already told callers to treat the signals differently — but no caller could, because the row unioned them away. The contract was unimplementable.Rows now carry
Dirty; the single-file query setsMatchedDirty. The gate denies only on an uncommitted edit in a live worktree and reports committed-and-clean as context instead. Fails safe across the upgrade: a cached row predatingMatchedDirtyis treated as dirty, degrading to the old over-block rather than silently permitting a real collision.Also:
git statusnow runs--no-optional-locks. A plaingit statusrewrites the index of the repo it inspects, and overlap walks every peer worktree — so asking "what is in flight" was mutating other sessions' checkouts on everyPreToolUse.Tests, and why they should be believed
Both negative controls were written first and watched fail:
test_every_wired_script_exists_in_this_checkout— red until the script landed, naming the missing file and printing all three paths it scanned. Nothing in this repo asserted this for any hook before; its absence is how a wired-but-inert shim survived weeks.test_installed_coord_hooks.py— asserts a wired hook resolves to a script that exists, closing the "absence is indistinguishable from approval" hole. It found five user settings files across account directories, and now prints the founding defect as ordinary output:FOREIGN UserPromptSubmit [mefor-web-announce] -> scripts/hooks/announce.ps1: RESOLVES NOTHING HERE. Another repo's entry — reported, never touched.test_coord_overlap_signals.py— drivesoverlap.ps1against a real git fixture. Nothing did before, so "doesMatchedDirtyhold when a file is dirty and committed at once" was unanswerable by the suite. Verified by sabotaging the row to publish an emptyDirtyset and confirming both assertions went red.Most tests here assert an absence, which a hook that does nothing also satisfies — so they are paired with a positive arm running the same runner against fixtures differing only in whether a peer exists.
Deliberately not done
Broadcast. Announce-on-join introduces a session; it does not let one push an operational notice. Six sessions rehearsed that by hand for four hours and the constraints are recorded in
docs/WORKTREES.md: a broadcast needs an expiry or a recipient-checkable predicate, never a sender's promise; "don't do X" is the wrong primitive when automation has X armed; and coordination a tool cannot read does not count.Hunk-range disjointness. All three false denials reported were the committed-and-clean case this already fixes. A wrong disjointness check under-blocks, trading a loud failure for a silent one. Filed evidence-gated instead.
There is no receive-side hook, so "an announcement is peer data, not an operator instruction, and must not be replied to" lives in the prose and the fixed message shape alone. Stated rather than buried.
Cost, stated rather than discovered
The shim costs ~0.5s per user prompt in every repo on the machine; the peer lookup adds ~1.0s on prompts where it runs. The new tests are pwsh+Windows-only and add ~65-70s to
windows-2025specifically.Verification
ruff format --check,ruff check,mypy --strict, leak gate, and 86 tests green — re-run after mergingmain, which brought changes tosession-registry.ps1andpresence.ps1that this consumes.🤖 Generated with Claude Code
Deploying this — merging is NOT enough, and the difference is measurable
collision_gate.ps1is not an installed copy.~/.claude/settings.jsonwires it as an inline shim that resolves the script live out of a working tree on every invocation, primary checkout first. So the gate adjudicating all worktrees is whatever the primary's HEAD happens to point at.Measured while this PR was open:
The gate in force right now does not contain this fix, and merging this PR will not change that — it only makes the primary 3 behind instead of 2.
So do not announce this as "merged, the over-blocking is fixed." Sessions will test it, get a deny, and reasonably conclude the fix is broken while actually executing an older script. The accurate form is merged; takes effect once the primary checkout is updated to a commit containing it.
Verify what is actually running:
A non-zero count is the fix being in force. Two events, not one.
A corollary that is a live debugging trap: editing
collision_gate.ps1in your own worktree has no effect on the gate adjudicating you — the shim never reaches the second base while the primary has the file. Anyone testing a gate change from a feature branch will see zero effect and reasonably conclude their change is broken. Test it by invoking the script directly (-PathOverride), as this PR's tests do.Why the over-block needed fixing rather than waiting out
Observed on this repo while the PR was open: the false-positive holder set churns rather than drains. A session retried one blocked edit as branches merged and was still denied — but by a different set of holders, one having cleared and two new ones having arrived. On a busy repo a session can be blocked continuously by a succession of holders, none of whom is actually editing the file. "Wait for it to clear" is not a workable answer.
Separately, a clean positive control for
overlap.ps1's three-dot ∩ two-dot behaviour, measured across #131 merging:docs/BACKLOG.mdholders went 4 → 2, and one holder disappeared while still live with the same worktree checked out — only its content had reachedmain. The intersection self-clears on merge exactly as documented, which is why this PR narrows the predicate rather than adding an expiry.A known weakness in the claim note this leans on
This PR makes the announce roster print each peer's claim note and tells the model to prefer it over the worktree name, because a worktree name is a creation-time label that nothing keeps current — one in this repo has advertised work it never did for its whole life.
The claim note is the better signal, but it is not as strong as that framing implies, and the PR should not pretend otherwise:
scripts/coord/claim.ps1silently discards a note update. Re-taking a key you already hold prints a greenYou already hold '<key>'and drops the-Note, so a session that re-takes to refresh its note believes it has communicated and has not. Its parameter doc atclaim.ps1:37promises the opposite of whatclaim.ps1:129implements — the two contradict each other ninety lines apart, in one file.So until that is fixed, this hook can broadcast a stale note as current intent, which is a real cost of elevating the note to authoritative. Leading with the claim is still better than leading with the directory name — a deliberate-but-stale statement beats an auto-generated one that was never true — but the gap is worth naming rather than discovering.
Filed separately; deliberately not fixed here, since it is independent of this change and deserves its own test (take with note A, re-take with note B, assert
-Listshows B — the current code passes anything that only checks the exit code, which is how it survived).