Skip to content

feat(events): relocate the hook event channel to a user-scoped state root (#494) #568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pbean merged 11 commits into from
Aug 13, 2026
Merged

feat(events): relocate the hook event channel to a user-scoped state root (#494) #568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
1483d97
feat(relay): importable event-write twin + `bmad-loop relay <Event>`
Aug 12, 2026
11d10f8
feat(state): user-scoped state root for the run control plane
Aug 12, 2026
a2ac5fb
feat(events): relocate the hook-event channel out of the project tree
Aug 13, 2026
2ef7e5d
feat(observability): make validate and diagnose honest about the relo…
Aug 13, 2026
ff8967d
feat(cleanup): collect the out-of-tree events channel with the run
Aug 13, 2026
6570e1e
docs(changelog): name the twin's write path, not the whole module
Aug 13, 2026
debce19
fix(runs): hold RuntimeError in the state-dir never-raise guards
Aug 13, 2026
5175f53
fix(runs): order the orphan sweep's reads, and refuse a relative stat…
Aug 13, 2026
f1f7554
docs(adapters): state that the bootstrap's keyword set grows
Aug 13, 2026
051752c
docs(cli): stop `relay`'s help claiming the installed hooks invoke it
Aug 13, 2026
95e622d
docs(adapters): unbreak the bootstrap-contract bullet's markdown
Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,33 @@ whose seams had diverged enough that several ports needed a different fix, and t

### Added

- **The hook-event channel moves out of the project tree (#494).** A run's session-completion
signals now land under a user-scoped state root — `$XDG_STATE_HOME/bmad-loop` (else
`~/.local/state/bmad-loop`), `%LOCALAPPDATA%\bmad-loop\state` on Windows, or wherever
`BMAD_LOOP_STATE_DIR` points (absolute paths only — the orchestrator and the session it
launches read the root from different working directories) — keyed
`<root>/<project>/<run-id>/events/`, so a branch switch, a
worktree mount or a rollback can no longer take a live run's control plane away.

- **Older relays keep working.** Sessions are told the directory via `BMAD_LOOP_EVENTS_DIR`; both
relays fall back to the in-tree `<run-dir>/events` and the orchestrator polls both locations.
`init` copies the relay into the project, so an upgraded orchestrator regularly drives sessions
whose relay predates the move — re-run `bmad-loop init` to refresh it.
- **`bmad-loop relay <Event>`** writes a session event without the copied-in script, on the same
contract (nothing on stdout, rc 0 always, silent no-op outside a driven session). `init` does
not point hooks at it yet — that retargeting is #461 Phase 2 — so it changes no run today. It
is backed
by a new `events.py`, whose write path an AST parity test holds byte-identical to the
stdlib-only relay's, and dispatches ahead of the shared error handler so a broken
`policy.toml` cannot fail a hook.
- **`validate` gains `hooks.relay-stale`** — the installed relay compared against the packaged
one, a warning that never moves the exit code (the fallback keeps a stale relay working).
`diagnose`'s `events` group now counts both locations; payload and schema unchanged.
- **`delete`/`archive`/`clean` collect the out-of-tree dir** with the run, and `clean` sweeps
orphans whose run dir is already gone (`--json`: `state_dirs_swept`, an additive field). An
archived tarball therefore no longer contains `events/` — consumed transient signals.
- `run`/`sweep` `--dry-run` previews the events directory a session would use.

- **Coding-CLI adapter registry: a new adapter class ships out-of-tree (#226).** The transport axis
has long been extensible out-of-tree; the CLI axis had no equivalent, so a CLI needing its own
adapter _class_ forced a name-branch in the run bootstrap. A profile's new `adapter` field names a
Expand Down
20 changes: 13 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -563,19 +563,25 @@ For `per_worktree`, set `editor_mode = "per_worktree"` with `[scm] isolation = "

## Environment variables

A handful of `BMAD_LOOP_*` variables override behavior at runtime, taking precedence over the policy file. Most operators only ever touch `BMAD_LOOP_MUX_BACKEND`; the other two are override/test hooks.
A handful of `BMAD_LOOP_*` variables override behavior at runtime, taking precedence over the policy file. Most operators only ever touch `BMAD_LOOP_MUX_BACKEND` and, on a host with an unusual home directory, `BMAD_LOOP_STATE_DIR`; the rest are override/test hooks.

| Variable | Value | Effect |
| ----------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BMAD_LOOP_MUX_BACKEND` | registered backend name (e.g. `tmux`, `psmux`) | Forces the terminal-multiplexer backend, outranking the `[mux] backend` policy key and auto-selection. A name matching no registered backend is an error — it never silently falls back. Unset ⇒ auto-select. |
| `BMAD_LOOP_PROCESS_HOST` | registered host name (e.g. `posix`, `windows`) | Forces the process-lifecycle host (an override/test hook). A name matching no registered host raises rather than silently using POSIX. Unset ⇒ this platform's default. |
| `BMAD_LOOP_SESSION_TIMEOUT_S` | seconds (float) | Overrides the per-session wall-clock budget (normally `limits.session_timeout_min × 60`) — mainly a test/E2E hook for sub-minute timeouts. A value that is not a finite positive number is ignored — non-positive, unparseable, or non-finite (`inf`, `1e999`), the last of which would otherwise disable the timeout outright. A large finite value is honoured. Unset ⇒ the policy value. |
| Variable | Value | Effect |
| ----------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BMAD_LOOP_MUX_BACKEND` | registered backend name (e.g. `tmux`, `psmux`) | Forces the terminal-multiplexer backend, outranking the `[mux] backend` policy key and auto-selection. A name matching no registered backend is an error — it never silently falls back. Unset ⇒ auto-select. |
| `BMAD_LOOP_PROCESS_HOST` | registered host name (e.g. `posix`, `windows`) | Forces the process-lifecycle host (an override/test hook). A name matching no registered host raises rather than silently using POSIX. Unset ⇒ this platform's default. |
| `BMAD_LOOP_STATE_DIR` | absolute directory path | Overrides the user-scoped **state root** — the out-of-tree home of per-run control-plane state, keyed `<root>/<project>/<run-id>/`. Used as the root itself, so nothing is appended to it. Must be **absolute**: the root is read both by the orchestrator and by the session it launches, which run from different working directories, so a relative value names two different places — bmad-loop refuses it rather than picking one. Unset ⇒ `$XDG_STATE_HOME/bmad-loop` when that names an absolute path, else `~/.local/state/bmad-loop`; on Windows `%LOCALAPPDATA%\bmad-loop\state`, else `%USERPROFILE%\AppData\Local\bmad-loop\state`. Set this when none of those is derivable or writable (a home on a network share, a locked-down service account). |
| `BMAD_LOOP_EVENTS_DIR` | directory path | **Session protocol, not an operator knob.** The orchestrator exports it into every session it drives, naming that run's hook-event directory under the state root; the hook relay writes there, falling back to the legacy in-tree `<run-dir>/events` when it is absent. Setting it yourself in a shell has no effect on a run (the engine overwrites it per session) and only misdirects a hand-invoked relay. |
| `BMAD_LOOP_SESSION_TIMEOUT_S` | seconds (float) | Overrides the per-session wall-clock budget (normally `limits.session_timeout_min × 60`) — mainly a test/E2E hook for sub-minute timeouts. A value that is not a finite positive number is ignored — non-positive, unparseable, or non-finite (`inf`, `1e999`), the last of which would otherwise disable the timeout outright. A large finite value is honoured. Unset ⇒ the policy value. |

Game-engine (Unity) runs read a wider `BMAD_LOOP_UNITY_*` / `BMAD_LOOP_ENGINE_*` set documented in the [Game Engine MCP guide](docs/game-engine-mcp-guide.md).

## Run state

Everything about a run lives in `.bmad-loop/runs/<run-id>/` (gitignored): `state.json` (resumable engine state), `journal.jsonl` (every decision), `events/` (hook signals), `tasks/<id>/` (per-session prompt + result + escalations, plus diagnostic breadcrumbs — `session-lifecycle.jsonl` records when a timeout fired, `heartbeat.json` is the wait loop's proof-of-life, `resultless-stops.jsonl` records give-up Stops), `logs/` (raw pane output, debugging only), `deferred/` (stashed specs from deferred stories), `resolve/<story>/` (escalation `context.json` + the resolve agent's `resolution.json`), `ATTENTION` (human-readable alerts), and — only while a graceful stop is pending — `stop-request.json` (the control file the engine consumes at the next item boundary).
Everything about a run lives in `.bmad-loop/runs/<run-id>/` (gitignored): `state.json` (resumable engine state), `journal.jsonl` (every decision), `tasks/<id>/` (per-session prompt + result + escalations, plus diagnostic breadcrumbs — `session-lifecycle.jsonl` records when a timeout fired, `heartbeat.json` is the wait loop's proof-of-life, `resultless-stops.jsonl` records give-up Stops), `logs/` (raw pane output, debugging only), `deferred/` (stashed specs from deferred stories), `resolve/<story>/` (escalation `context.json` + the resolve agent's `resolution.json`), `ATTENTION` (human-readable alerts), and — only while a graceful stop is pending — `stop-request.json` (the control file the engine consumes at the next item boundary).

One piece deliberately lives elsewhere: the **hook-event channel** (the session completion signals the orchestrator waits on) sits under the user-scoped state root at `<state root>/<project>/<run-id>/events/`, outside the project tree — a branch switch, a worktree mount or a rollback must not be able to take a live run's control plane away. See `BMAD_LOOP_STATE_DIR` above for where that root resolves. The orchestrator also keeps polling the old in-tree `events/` location, so a project whose installed hook relay predates the move still completes its sessions; re-run `bmad-loop init` to refresh the relay.

That out-of-tree directory is collected with the run: `delete`, `archive` and `clean` remove it alongside the run dir, and `clean` also sweeps this project's orphans there — control planes whose run dir is already gone, e.g. from a hand-removed run (`clean --dry-run` previews the count; `--json` reports it as `state_dirs_swept`). Two consequences worth knowing: an archived run's tarball no longer contains `events/` (transient completion signals, consumed while the run was live), and a project that is deleted, moved or renamed leaves its old subtree behind — the key is derived from the project's resolved path, so after a move the project itself now keys somewhere new and nothing can name the old key to sweep it. Remove it by hand if you care; it is events-sized, not run-sized.

A run can be stopped two ways. A **hard stop** (`bmad-loop stop`, TUI `x`, Ctrl+C) SIGTERMs the engine mid-item and always kills the agent session. A **graceful stop** (`bmad-loop stop --graceful`, TUI `S`) instead writes `stop-request.json` — no signal, so it works on every platform and multiplexer backend — which the engine consumes at the next item boundary: the in-flight story (or sweep bundle) finishes through commit — or, mid-triage, the sweep's triage session completes and no bundles start — the run finalizes as `stopped` (not `finished`) and stays resumable, and pending auto-sweeps are suppressed. Its session teardown follows `cleanup_session_on_finish` like a normal finish, rather than the hard stop's unconditional kill; a hard stop always supersedes a pending graceful request.

Expand Down
Loading