Struct BrokerState 

pub struct BrokerState {
    pub log_path: Option<PathBuf>,
    pub learnings: Option<SharedLearnings>,
    pub verify_on_commit_nudge: bool,
    pub role_gating: Option<RoleGatingContext>,
    /* private fields */
}

Shared broker state.

Wraps BrokerStateInner in an RwLock for concurrent read access. The sequence counter is a standalone AtomicU64 outside the lock so that sequence numbers can be allocated without coupling to the write lock.

Fields

log_path: Option<PathBuf>

Optional path for periodic log flush to disk.

learnings: Option<SharedLearnings>

Optional learnings aggregator. Populated when supervisor + learnings mode is active; the publish path forwards every observed message.

verify_on_commit_nudge: bool

When true, an agent.artifact { status: "committed" } triggers a broker-emitted BrokerMessage::VerifyNow nudge to the supervisor inbox so per-commit verification fires on an explicit event. Resolved from [supervisor].verify_on_commit_nudge (default true) at session boot and threaded in via BrokerState::with_verify_on_commit_nudge.

role_gating: Option<RoleGatingContext>

opsx role-gating context. When Some and active (OpenSpec engine + non-off mode), the publish path runs the role-gating guard on every agent.artifact { status: "committed" }. None (the default, and non-OpenSpec sessions) leaves the guard inert. Threaded in via BrokerState::with_role_gating.

Implementations

impl BrokerState

pub fn new(log_path: Option<PathBuf>) -> Self

Creates a new empty broker state.

pub fn with_role_gating(self, ctx: RoleGatingContext) -> Self

Attaches the opsx role-gating context. Call before start_broker so the publish path observes it from the first committed artifact. Passing a context whose mode is off or whose engine is not OpenSpec leaves the guard inert (the guard re-checks crate::opsx::RoleGatingContext::is_active).

pub fn with_verify_on_commit_nudge(self, enabled: bool) -> Self

Sets whether committed artifacts emit a BrokerMessage::VerifyNow nudge to the supervisor inbox. Call before start_broker so the publish path observes the resolved value from the first message.

pub fn with_seeded_cli(self, agent_id: &str, cli: &str) -> Self

Authoritatively seeds an agent’s CLI into the roster’s CLI map.

git-paw knows every pane’s CLI at launch (the supervisor’s from [supervisor].cli/default_cli, each agent’s from the resolved agent CLI), so the launcher seeds those known values rather than depending on the agent to self-report via agent.status. This is the only source for the supervisor’s CLI column, since the supervisor is not a filesystem watch target (W15-15). A blank cli is ignored so a missing config value never clobbers the map. Call before start_broker so the first /status snapshot is correct.

pub fn attach_learnings(&mut self, aggregator: SharedLearnings)

Attaches a learnings aggregator. Replaces any previously attached instance. Must be called before start_broker so the publish path observes every message from the first one.

pub fn set_republish_working_ttl(&self, ttl: Duration)

Sets the post-commit re-entry TTL consulted by the filesystem watcher and the committed -> working transition in update_agent_record (bug 8). Duration::ZERO disables the auto-republish behaviour.

pub fn set_watcher_shutdown_rx(&self, rx: Receiver<bool>)

Records the shared watcher shutdown receiver so the POST /watch handler can clone it when spawning a live-registered watcher. Called once in start_broker_with before the start-time watchers spawn; subsequent calls are ignored (the receiver is set-once).

pub fn watcher_shutdown_rx(&self) -> Option<Receiver<bool>>

Returns a clone of the shared watcher shutdown receiver if the broker has spawned its watchers, or None otherwise (e.g. router-only unit tests). The POST /watch handler uses this to enroll a hot-added watcher in the shared shutdown signal.

pub fn register_watch_target(&self, target: &WatchTarget) -> bool

Registers a worktree as a live watch target for POST /watch.

Bookkeeping only — the caller spawns the actual watcher::watch_worktree task when this returns true. Idempotent: the worktree path is the key, so re-registering an already-watched path returns false and the caller spawns nothing (no duplicate watcher). On a fresh path it seeds the agent’s CLI label and inbox queue exactly as the start-time targets are seeded in start_broker_with, so the agent surfaces in /status and receives peer broadcasts on the same terms.

pub fn forget_watch_target(&self, worktree_path: &Path)

Drops a worktree from the live watch-target set so a later re-registration of the same path spawns a fresh watcher. Called by a watcher task when it detects its worktree has disappeared (the prune path for git paw remove).

pub fn read(&self) -> RwLockReadGuard<'_, BrokerStateInner>

Acquires a read lock on the inner state.

Panics

Panics if the lock is poisoned (a thread panicked while holding it).

pub fn write(&self) -> RwLockWriteGuard<'_, BrokerStateInner>

Acquires a write lock on the inner state.

Panics

Panics if the lock is poisoned (a thread panicked while holding it).

pub fn next_seq(&self) -> u64

Atomically allocates the next sequence number (starting at 1).

pub fn uptime_seconds(&self) -> u64

Returns the number of seconds since the broker was started.

Used by the HTTP /status handler to report uptime.

Trait Implementations

impl Debug for BrokerState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.