Demote metadata and statusline to projections

[TraderSamwise]

Summary

• label debug-state sources by authority/projection role and ignore stale metadata identity fields
• cut metadata label shadow writes from agent rename and scrub labels/backend ids from metadata projections
• derive statusline task counts from runtime exchange and bound statusline metadata to known projection sessions
• retire local .aimux/statusline.json reads and document notification exchange authority

Verification

• yarn verify
• yarn build
• pre-push yarn verify

Summary by CodeRabbit

Release Notes

• Documentation

  • Added projection contract documentation clarifying authority boundaries
  • Updated runtime architecture documentation for metadata, notifications, and statusline handling

• Bug Fixes

  • Local statusline and metadata files (.aimux/statusline.json, .aimux/metadata.json) are now ignored; only global project state is used
  • Fixed session identity resolution to ignore stale metadata fields
  • Statusline snapshot now derives task counts from runtime state instead of hardcoded values

• Refactor

  • Restructured data authority model to clearly separate authoritative vs. projected data sources
  • Removed deprecated label field from stored session metadata
  • Updated notifications storage architecture

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 655dfb15-8125-4f89-b8a0-45d7dccd0286

📥 Commits

Reviewing files that changed from the base of the PR and between 333702d and 81f98d1.

📒 Files selected for processing (17)

• docs/runtime-authority-dead-paths.md
• docs/runtime-authority-inventory.md
• docs/runtime-core-hard-cut-roadmap.md
• docs/runtime-projection-contract.md
• src/alert-display.ts
• src/debug-state.test.ts
• src/debug-state.ts
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/metadata-store.test.ts
• src/metadata-store.ts
• src/multiplexer/persistence-methods.test.ts
• src/multiplexer/persistence-methods.ts
• src/project-scanner.test.ts
• src/project-scanner.ts
• src/tmux/statusline.test.ts
• src/tmux/statusline.ts

💤 Files with no reviewable changes (2)

• src/alert-display.ts
• src/metadata-server.ts

---

📝 Walkthrough

Walkthrough

This PR enforces the runtime "hard cut" between authoritative topology/exchange and projection artifacts: metadata identity fields are removed and scrubbed, statusline is read exclusively from global registry state, and debug-state sources are labeled with their authority role.

Changes

Authority/Projection Contract Implementation

Layer / File(s)	Summary
Projection contract documentation docs/runtime-projection-contract.md, docs/runtime-authority-dead-paths.md, docs/runtime-authority-inventory.md, docs/runtime-core-hard-cut-roadmap.md	New projection contract document defines authority boundary between runtime-topology.yaml/runtime-exchange.yaml and projection artifacts (metadata.json, statusline.json, notification-context.json); existing docs updated to specify metadata authority moves to global metadata.json, notifications move to runtime-exchange CUT model, statusline reads from global registry state only, and local .aimux/ files are retired.
Metadata identity field scrubbing src/metadata-store.ts, src/metadata-store.test.ts	SessionMetadata interface removes optional label field; scrubBackendSessionIds helper is replaced with scrubProjectionAuthorityFields to remove both backendSessionId and label on metadata load/write; test mocks updated to verify scrubbing behavior.
Metadata server write enforcement src/metadata-server.ts, src/metadata-server.test.ts	/agents/rename endpoint no longer writes label to metadata store; test verifies delegation to lifecycle.renameAgent and confirms loadMetadataState returns undefined for the renamed session (no persisted metadata).
Alert display context update src/alert-display.ts	metadataDisplayContext drops the label property assignment, leaving only worktreePath, worktreeName, and branch.
Debug-state source role classification src/debug-state.ts, src/debug-state.test.ts	New SourceRoleDescriptor interface and DEBUG_STATE_SOURCE_ROLES constant map each debug-state source to its authority role; filterMetadata updated to match on sessionId/worktree/branch/cwd only (no longer uses backendSessionId/label); tests verify source role classification and that stale metadata projection fields do not resolve.
Global statusline reads and projection sanitization src/project-scanner.ts, src/project-scanner.test.ts, src/tmux/statusline.ts, src/tmux/statusline.test.ts	scanProject now exclusively uses global registry-state statusline.json when available, ignoring local .aimux/statusline.json; new sanitizeStatuslineProjection helper filters statusline metadata to include only entries for known session/teammate IDs; tests verify local statusline is ignored and ghost metadata entries are dropped from loaded projection.
Statusline tasks from runtime-exchange authority src/multiplexer/persistence-methods.ts, src/multiplexer/persistence-methods.test.ts	New exchangeTaskCounts() helper reads task status counts from runtime-exchange store; buildStatuslineSnapshot and dashboard statusline client now use dynamic task counts (pending, assigned, in_progress, blocked) from exchange instead of hardcoded zeroes; test verifies counts are correctly derived.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• TraderSamwise/aimux#30: Statusline task counts now derive from runtime-exchange store via createRuntimeExchangeStore, which depends on the runtime topology+exchange schema work introduced in PR #30.
• TraderSamwise/aimux#28: The removal of legacy metadata identity fields and exclusive use of global statusline directly align with PR #28's broader removal of legacy lifecycle paths from metadata/tmux in favor of runtime-core/topology authority.
• TraderSamwise/aimux#32: Both PRs modify src/debug-state.ts/src/debug-state.test.ts to classify debug-state sources by authority role; this PR focuses on metadata/projection filtering while PR #32 focuses on runtime topology/service classification.

Poem

🐰 The hard cut comes clear,
Projection fields disappear—
Global state shines here,
Exchange holds the truth,
Dead paths fade away fast. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title "Demote metadata and statusline to projections" clearly and concisely summarizes the main change, matching the primary objective of reclassifying metadata and statusline from authority to projections.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch phase/metadata-notifications-statusline-projections

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}