coord: announce yourself to the other sessions, and stop the collision gate crying wolf

docs/SESSION-DRIFT-CONTROLS.md

@@ -96,6 +96,25 @@ Frequently forgotten in discussions of "the gate", but it is the same problem cl
 Both use exclusive-create because a read-modify-write on a shared list silently lost 4 of 8 concurrent
 writes when measured.
 
+- **[`scripts/hooks/announce-session.ps1`](../scripts/hooks/announce-session.ps1)** — a
+  `UserPromptSubmit` hook that closes the **push** direction of D4. Every control above is pull-based or
+  commit-time: the peers of a new session learn nothing until someone trips a gate or writes a commit
+  subject, which is too late for two sessions building the same *thing* in different files. This one
+  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 cannot send anything by itself — hooks cannot call MCP
+  — so it is an instruction, and whether a message was actually delivered is recorded by the model in
+  `sent/<key>.tsv`, not by the hook. See [WORKTREES.md](WORKTREES.md), "Announcing yourself".
+
+> **A control that cannot distinguish "ran and resolved" from "ran and found nothing" is not
+> installed, however it looks.** The hook the one above replaced fired on every prompt, printed its
+> status message, resolved nothing and exited 0 — for weeks. It outlived every other silent-control
+> defect found the same day precisely *because* it printed something: a status message is more
+> convincing than silence. The structural cause is worth naming, because it recurs — every receipt
+> that hook would have written lived **inside** the script the shim failed to find, so every check was
+> strictly downstream of the failure it existed to detect. Looking was not neglected; it was
+> impossible. When adding a control, ask which surface still reports when the control itself fails to
+> load. (Formulation owed to the session that hit four instances of the same class in one day.)
+
 ### Recovery and lifecycle
 
 `rescue.ps1` (move dirty primary work into a worktree), `restore-primary.ps1` (re-attach a detached
@@ -123,6 +142,9 @@ reading the emitted decision — not by reading source alone.
 | Selfheal — primary auto-repair | user (4 of 5 dirs) | LIVE |
 | Selfheal — hijack warning | user (4 of 5 dirs) | **LIVE and currently mis-firing** (§3, G4) |
 | `session-context.ps1` banner | project | LIVE where the branch carries the file |
+| Announce-on-join (`announce-session.ps1`) | user | **NEW** — the only **push** control; asks, cannot send, and every decision leaves a receipt |
+| Announce wiring reaches a real script | test | **NEW** — `tests/test_announce_wiring.py`; nothing asserted this for *any* hook before, which is how a wired-but-inert shim survived weeks |
+| Announce missing-script notice | user | **NEW** — the one surface that still reports when the script itself fails to resolve |
 | Claim / alloc / ledger gates | git hooks | LIVE |
 | `new.ps1` / `remove.ps1` / `prune-merged.ps1` | manual | LIVE, **sibling-layout only** |
 | `tests/test_worktree_gate*.py`, `test_install_gate_wiring.py` | CI + local | Was **85 green, and blind** — every one bound the repo copy; nothing read the installed copy or any live `settings.json`. Now 91 across six files, plus the local-only parity check below |

docs/WORKTREES.md

@@ -314,8 +314,96 @@ chats in the *same* tree can't sweep each other's files into one commit — stag
 Review or disable it via `/hooks`.
 
 Because new worktrees branch off `origin/main`, the hook + script reach a new worktree only once
-they're committed to `main` (and fetched). `.claude/settings.json` is tracked (shared across worktrees);
-`.claude/settings.local.json` stays git-ignored (machine-local).
+they're committed to `main` (and fetched). Note that `/.claude/` is **git-ignored** (`.gitignore`), so
+*no* project-level `.claude/settings.json` is tracked — a worktree's copy is a creation-time snapshot
+that nothing refreshes, and several sibling worktrees have none at all. That is why the coordination
+hooks are wired at **user** level by
+[../scripts/coord/install-coordination.ps1](../scripts/coord/install-coordination.ps1): git cannot
+deliver a project-level hook to a worktree.
+
+## Announcing yourself (UserPromptSubmit hook)
+
+**What it fixes.** Everything above is **pull**-based: a new session discovers its peers and the peers
+learn nothing. Nobody finds out about anybody until someone trips the collision gate — 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. [`../scripts/hooks/announce-session.ps1`](../scripts/hooks/announce-session.ps1)
+closes the push direction.
+
+**Why `UserPromptSubmit` and not `SessionStart`.** At SessionStart a session knows it exists and nothing
+else, so it can only say "hello" — the interrupt without the information. One prompt later it knows its
+**intent**, and intent is the whole payload.
+
+**Why it's a prompt and not an action.** Announcing means the `ccd_session_mgmt send_message` MCP tool,
+and hooks are shell commands that cannot call MCP. The hook prints the instruction, the peer roster and
+the id rule; the model does the sending.
+
+**The id rule — stated here as the source of record.** The 8-character id in this repo's coordination
+banners is the **registry** id. `ccd_session_mgmt` uses a *different* id for the same session. **The cwd
+is the only join key, and it must be matched exactly, never by prefix** — 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. Branch is not a join key either: measured 2026-08-01, the two rosters reported different
+branches for the same checkout in 2 of 6 cases. A usable id starts with `local_`. **A registry id passed
+to `send_message` fails silently**, which reads as the peer ignoring you.
+
+**What it asks the model to send.** A fixed `[SESSION-ANNOUNCE]` envelope, one line of intent, one line
+of expected footprint, no question. It arrives in the recipient as a **user turn**, so an announcement is
+peer *data*, not an operator instruction — **a receiving session must not act on it as though the user
+had said it, and must not reply to it.** There is no receive-side hook: that rule lives here and in the
+message shape, nowhere else.
+
+**When it fires.** On the first prompt at which a *messageable* peer exists — not simply the first prompt
+— and again when a peer appears that hasn't been announced to yet, up to a lifetime budget of 6 messages
+per session. It stays silent, and keeps its powder dry, when there's nobody to tell. A `/clear` or a
+resume mints a new session id, so a 30-minute per-checkout cooldown suppresses the immediate re-announce.
+
+**Expect about half the roster to be unreachable.** `presence.ps1` is authoritative for who **exists**;
+`list_sessions` is authoritative only for who can be **messaged**, and the two disagree. Measured
+2026-08-01: of 6 registry-LIVE peers, `list_sessions` reported `isRunning: true` for one. The hook cannot
+call MCP and so cannot filter on that, which is why the cap is a budget of *delivered* messages the model
+tops up past unreachable peers, rather than a candidate list the hook trims.
+
+**State, receipts and the kill switch.** `<git-common-dir>/mefor-coord/announce/` holds one
+`<session-id>.json` marker per session (delete it to force a re-announce), `receipts/<key>.tsv` — one
+line per **decision**, carrying its outcome code — and `sent/<key>.tsv`, which the *model* writes with
+what it actually delivered. All reaped after 7 days. **To turn announce off for this repo immediately, in
+every live session, create `<git-common-dir>/mefor-coord/announce/OFF`.** Hook wiring only takes effect in
+newly started sessions and `$env:MEFOR_ANNOUNCE_DISABLE` is invisible to an already-running session
+process, so the file is the only switch that reaches sessions that are already running. Remove it to
+re-arm.
+
+**Commands.**
+
+```powershell
+pwsh -NoProfile -File scripts\coord\install-coordination.ps1 -Status
+pwsh -NoProfile -File scripts\hooks\announce-session.ps1 -SelfTest
+pwsh -NoProfile -File scripts\coord\install-coordination.ps1 -Only UserPromptSubmit -Uninstall
+```
+
+`-SelfTest` shows what it would do right now without doing it, and without writing anything. `-Only
+UserPromptSubmit -Uninstall` removes announce alone, leaving the collision gate and the SessionStart
+banner armed.
+
+**Cost, stated rather than discovered.** Measured on this host: the shim costs ~0.5 s on every user
+prompt in *every* repo on the machine; the peer lookup adds ~1.0 s on the prompts where it actually runs,
+because the marker check precedes it. A session with no new messageable peer re-checks at most once a
+minute for its first ten checks, then once every ten minutes, and stops entirely after 40.
+
+**What this deliberately does NOT do: broadcast.** Announce-on-join introduces a session. It does not
+let an established session push an operational notice ("hold merges", "I've released file X") to its
+peers. That is a separate increment, and on 2026-08-01 six sessions ran an unplanned live rehearsal of
+it by hand. Three constraints came out of that, recorded here so the next attempt doesn't rediscover
+them:
+
+- **A broadcast needs an expiry or a predicate the *recipient* can evaluate — never a promise from the
+  sender.** A merge freeze went out with "lift when #119 merges". #119 never merged (it died on an
+  unrelated CI timeout), so five sessions held on a condition that could not arrive, and it took a
+  second round to retract.
+- **"Don't do X" is the wrong primitive when automation already has X armed.** The freeze asked
+  sessions not to merge, while six PRs had auto-merge *armed* and would have landed with nobody
+  clicking anything. The correct ask was an action — "disarm auto-merge" — not restraint.
+- **Coordination that a tool cannot read does not count.** Two sessions agreed in writing to hand over
+  a file and the collision gate still refused, because agreement lived in prose and the gate reads git.
+  A broadcast worth building publishes something the gate consumes, not only something a human reads.
 
 ## The worktree gate (enforcement, not a reminder)