Windows: narrowed but non-zero check-to-write race in the hook relay's event write

[pbean]

What

On Windows the hook relay's event write still has an open (but narrowed)
check-to-write window. src/bmad_loop/data/bmad_loop_hook.py::_write_event
refuses a redirected events/ dir (symlink or junction), then — on the fallback
path only — re-resolves the directory by path for the os.open and the
os.replace.

PR #493 narrowed this: the redirect check runs again after the payload is
written and before it is published, so a junction that is swapped in and left
in place is refused and the temp file removed. What remains is a
swap-and-restore inside the window: replace events/ with a junction, let the
relay create its temp file inside the attacker's directory, then restore the
real directory before the post-write check runs.

Why it is not already fixed

POSIX closes this properly — the create+rename are anchored to a dir_fd opened
O_RDONLY|O_DIRECTORY|O_NOFOLLOW, so no later path resolution happens.

Windows has no equivalent reachable from the standard library:
os.supports_dir_fd is empty there (dir_fd is implemented with the POSIX *at
calls), and Python exposes no handle-relative open. Closing it properly needs a
directory handle from CreateFileW with
FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT, and then
NtCreateFile with OBJECT_ATTRIBUTES.RootDirectory set to it — i.e. ctypes
against ntdll, inside a relay that is stdlib-only by contract and runs
under whatever interpreter the host happens to have. That is disproportionate to
the residual risk and carries its own hazard: a bug in it stops hook delivery on
Windows, which stalls every run — the exact harm being defended against.

Residual risk

Low. The attacker must win a precisely-timed race against a hook that fires at
moments they do not control, and must restore the real directory immediately
after. Failing the race in either direction is safe: a persistent junction is
refused (before or after the write), and a refusal degrades to the same
session_timeout_min path the run would have hit anyway. No silent redirect
survives unless the restore is perfectly timed.

Options if this is ever picked up

1. Accept and document (status quo). The narrowed window is recorded in the
   _write_event docstring.
2. ctypes + NtCreateFile handle-relative open on Windows. Correct, but a
   large Windows-CI-only-testable surface in a stdlib-only relay.
3. Move the relay's event writes out of the agent-writable tree entirely, which
   removes the attacker's ability to touch events/ at all. This overlaps with
   the direction of init vendors the hook relay into the agent-writable workspace, turning a file-write primitive into unattended persistent code execution #461 Phase 2 and is probably the cheapest real close.

Option 3 is the one worth evaluating first.

Follow-up from #461 Phase 1 (PR #493), raised by an automated reviewer on that PR.

[coderabbitai]

🔗 Related PRs

#170 - fix(hooks): recognize antigravity's registered relay in validate + probe (#159) [merged]
#385 - fix(install): scope the worktree git-add shield per-worktree (#384) [merged]
#434 - fix(adapters): seam-owned psmux option-key namespace, kill-order containment [merged]
#448 - fix(install): make provisioning total across filesystem faults [merged]
#493 - fix(#461): symlink-safe hook relay event write + validate stats the relay [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[pbean]

Scoping correction from a later review round on #493: there are two open windows on
the Windows fallback, not one. This issue's body describes only the first.

1. Swap-and-restore around the create (as filed): the temp file lands in the
   attacker's directory, and the post-write check sees a restored real directory.
2. Swap after the post-write check, before the publish: the temp file was written to
   the real directory, but os.replace re-resolves events_dir by path.

Both arms of (2) measured, forcing the fallback and swapping immediately before the real
os.replace:

• Target dir empty → os.replace raises FileNotFoundError (source is in the real dir,
  the path now points elsewhere) → OSError → return 0. Nothing lands in the
  attacker's dir.
• Target dir pre-seeded with <name>.json.tmp → os.replace renames the attacker's own
  planted file inside the attacker's own directory. The relay's payload never leaves
  the real dir; it stays as an orphan .tmp, which SignalWatcher.poll skips on the
  .json suffix filter.

So (2) does not redirect the payload either. Both windows end where a refusal ends — no
event, run waits out session_timeout_min — which is what an attacker gets for free by
leaving a redirect in place and being refused deterministically. Winning either race
buys no capability beyond what is already free, which is the real reason to accept the
residual; the stdlib-reachability argument below is the secondary one.

One remedy to rule out explicitly: unlinking the temp file when publication fails does
not help. Under a swap, tmp_path resolves through the redirect, so the cleanup would
unlink inside the attacker's directory and leave the real orphan behind. The inert .tmp
is the better outcome.

Stdlib reachability re-verified against current docs (3.14.7 and the 3.16.0a0 dev tree),
not from memory: dir_fd is implemented with the POSIX *at() calls, os.O_NOFOLLOW
and O_DIRECTORY are documented Unix-only, and os exposes no Windows handle-relative
create or rename. Option 2 (ctypes + NtCreateFile) and option 3 (Phase 2 moving the
relay out of the agent-writable tree) stand as written, and option 3 is still the
cheapest real close.

The _write_event docstring now records both windows and what each yields (#493
9933b11).

[pbean]

Triage 2026-08-08: verified — the Windows fallback re-resolve (data/bmad_loop_hook.py:146-164) leaves the narrowed race, and the residual is named and accepted in the docstring (:103-112). Decision: accept the documented residual, or take option 3 — move event writes out of the agent-writable tree entirely. Option 3 is the same shape the PR #238 rework needs (extracting #493's hardened write primitive), so if #238 proceeds, take option 3 there.

[pbean]

Maintainer decision 2026-08-08: option 3 — move the relay's event writes out of the agent-writable tree, landing in the PR #238 rework (extract #493's hardened primitive; the relocation and the extraction are one change). With events/ somewhere sessions cannot write, the check-to-write race class disappears and _is_link_like becomes belt-and-braces. The ctypes/NtCreateFile route (option 2) is declined: a large Windows-only ntdll surface inside the stdlib-only relay risks stalling every Windows run — the exact harm being defended. Shares the new out-of-tree control-plane root with #498's baseline relocation.