Module metadata 

Authoritative writer for session metadata fields (title, pinned, …).

All callers that mutate session metadata MUST go through this service. Each method follows a fixed pipeline so that title/pinned writes never diverge in subtle ways (load order, version bump, save semantics, event shape):

1. Trim / validate input (fail-fast before acquiring the lock).
2. persistence.acquire_lock(session_id) — serialise all writes for this session so that commit order == publish order.
3. storage.load_session(session_id) — pick up the latest authoritative copy from disk (not a runner-held session that may have stale metadata).
4. Re-check preconditions inside the lock (e.g. is_untitled for apply_generated_title when not forced; equality short-circuit for setters that would be a no-op).
5. Mutate the field, bump title_version (for title) and always bump metadata_version, set updated_at.
6. Plain storage.save_session(&session) — no merge needed because we loaded the latest copy inside the lock and no other writer for this session could have interleaved.
7. Refresh the in-memory cache (state.sessions).
8. Build the corresponding AgentEvent from the final persisted session and publish via publish_replayable_session_event.

Authority rules

• set_title / apply_generated_title: the only authoritative writers for title and title_version. The runtime engine, scheduler, and tool execution paths are non-authoritative and must stay on merge_save_session / merge_save_runtime without touching title directly.
• set_pinned: the only authoritative writer for pinned.
• Only these methods bump metadata_version. Runtime paths never bump it, so merge_save_session / merge_save_runtime can use it as a staleness signal for the entire authoritative metadata group.

Structs

SessionMetadataService

Enums

MetadataError

Errors returned by SessionMetadataService.

Type Aliases

MetadataChange

Outcome of a metadata mutation.