Fix merge conflicts intelligently:
- package.json: Use main's test script pattern (tests/guards/*.test.mjs && tests/**/*.test.ts)
- src/app/api/events/route.ts: Merge polling logic with telemetry event emission
- src/hooks/use-beads-subscription.ts: Merge event type handling (issues/telemetry/activity)
All changes preserve the new telemetry-based architecture while accepting
main's improved test coverage patterns.
- Fix command injection in bb-init.mjs by using execFileSync with argument arrays
- Fix parser.ts skipAgentFilter option not being respected
- Fix src/app/globals.css truncated CSS rule causing parse errors
- Fix status-badge.tsx BeadStatus type import from canonical source
- Fix agent-registry.ts missing 'agent' prefix in callBdAgentShow
- Fix tools/bb.ts null data access for activity-lease command
- Fix src/app/api/sessions/route.ts projectRoot not passed to listAgents
- Update package.json test script to include all test files
- Fix tailwind.config.ts content glob missing UI components
- Remove .beadboard/agent/runtime/existing-agent.pid and add .gitignore rule
Co-authored-by: openhands <openhands@all-hands.dev>
STORY:
shadcn/ui components expect @/lib/utils to exist for the cn() helper.
Our project uses src/lib/, but shadcn creates lib/ at root.
COLLABORATION:
Created lib/utils.ts with the cn() function to satisfy shadcn imports.
This coexists with src/lib/utils.ts - both export the same function.
VERIFICATION:
- npm run typecheck: PASS
The .beadboard directory in user profile stores:
- projects.json: multi-project registry
- agent/: agent session data
This is the Windows-first location for machine-local BeadBoard config.
STORY:
Development requires supporting scripts and comprehensive test coverage.
This commit adds utility scripts and extends test suites.
COLLABORATION:
- scripts/capture-sessions.mjs: Screenshot capture for sessions hub
- scripts/capture-timeline.mjs: Timeline view capture utility
- sessions-header-logic.ts: Session header business logic
- Additional test files for sessions, hooks, and snapshot diffing
STORY:
Major epics require upfront planning documentation. These docs capture
the design decisions, architecture, and rollout maps for the
Agent System Overhaul (bb-buff) and Unified UX (bb-ui2) epics.
COLLABORATION:
- 2026-02-14-operative-protocol-design.md: ZFC state machine design
- 2026-02-14-super-agent-buff-roadmap.md: buff epic architecture
- 2026-02-15-unified-ux-prd.md: UI epic product requirements
- docs/protocols/: protocol specifications
These documents serve as the source of truth for implementation decisions
and help future contributors understand the design rationale.
STORY:
Agent identities were stored in a local JSON registry, but they should
be first-class beads visible in the BeadBoard system. This consolidates
agent identity to bd CLI as the source of truth.
COLLABORATION:
Replaced local JSON registry with bd CLI wrapper in agent-registry.ts:
- All agent operations now delegate to bd CLI
- Agents appear as team-visible beads with gt:agent label
- Identity isolation prevents agent beads from polluting mission lists
The consolidation makes agents visible to the entire team and ensures
consistent identity management across all tools.
DELIVERABLES:
- src/lib/agent-registry.ts refactored to bd CLI wrapper
- tests/lib/agent-registry-bd.test.ts for bd integration
- tools/bb.ts updated for consolidated identity ops
VERIFICATION:
- All registry tests PASS
- Agents appear on agent page but NOT in task lists
- Quality gates (typecheck, lint) GREEN
CLOSES: bb-1y7
EPIC: bb-u6f
STORY:
The existing ReactFlow dependency graph lived in the /graph page, but
the Unified UX needs it as a reusable component for the graph tab.
COLLABORATION:
Extracted the core ReactFlow visualization into WorkflowGraph component:
Interface:
- beads: BeadIssue[] to render as nodes
- selectedId?: currently selected bead
- onSelect?: selection callback
- className?: styling override
- hideClosed?: filter closed beads
Features preserved:
- Dagre layout for automatic positioning
- Edge rendering with BLOCKS labels
- fitView() on mount via useReactFlow
- Existing styling and hover states
The original /graph page can now use this component or serve as reference.
DELIVERABLES:
- src/components/shared/workflow-graph.tsx
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS
CLOSES: bb-ui2.19
BLOCKS: bb-ui2.20
STORY:
The Swarm view needs to show epics as "swarms" - groups of agents
working together on a mission. This requires aggregating bead data
by swarm/epic and computing health statistics.
COLLABORATION:
Created buildSwarmCards function that transforms epic + agent data:
SwarmCard interface:
- id, title, status
- stats: { completed, active, ready, blocked, total }
- agents: AgentRoster[] with liveness
- attention: blocked tasks + stuck agents needing attention
- lastActivity
We also created swarm-molecules.ts for molecular composition patterns
used by the swarm orchestration layer.
DELIVERABLES:
- src/lib/swarm-cards.ts with SwarmCard, AgentRoster types
- src/lib/swarm-molecules.ts for molecular composition
- tests/lib/swarm-cards.test.ts
- tests/lib/swarm-molecules.test.ts
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS
CLOSES: bb-ui2.15
BLOCKS: bb-ui2.16, bb-ui2.17
STORY:
The Social view needs to transform raw BeadIssue data into renderable
SocialCard objects. This includes computing blocked/blocking relationships
from dependencies and extracting agent assignments.
COLLABORATION:
Created buildSocialCards function that transforms BeadIssue → SocialCard:
SocialCard interface:
- id, title, status
- blockedBy: tasks this task depends on
- blocking: tasks that depend on this task
- agents: assigned agents with liveness
- lastActivity: most recent event
The function derives blockedBy from depends_on dependencies and blocking
from blocked_by reverse dependencies, creating a complete picture of
task relationships for the activity feed.
DELIVERABLES:
- src/lib/social-cards.ts with SocialCard interface and builder
- tests/lib/social-cards.test.ts
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS
CLOSES: bb-ui2.10
BLOCKS: bb-ui2.11, bb-ui2.12
STORY:
The Unified UX needs URL as the single source of truth for view state.
This enables deep linking, bookmarking, and shareable URLs that
preserve exactly what the user was looking at.
COLLABORATION:
Created useUrlState hook using Next.js useSearchParams and useRouter:
Interface:
- view: 'social' | 'graph' | 'swarm' (default: social)
- taskId: selected task ID (for detail panel)
- swarmId: selected swarm ID
- panel: 'open' | 'closed' (detail panel state)
- graphTab: 'flow' | 'overview' (graph view mode)
URL Patterns:
- /?view=social
- /?view=social&task=bb-buff.1&panel=open
- /?view=swarm&swarm=bb-buff
- /?view=graph&task=bb-buff.1&graphTab=flow
The hook uses router.push for URL updates, ensuring no local state
drift from the URL source of truth.
DELIVERABLES:
- src/hooks/use-url-state.ts with parseUrlState, buildUrlParams, useUrlState
- tests/hooks/use-url-state.test.ts with 18+ tests
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS (all tests including new ones)
CLOSES: bb-ui2.4
BLOCKS: bb-ui2.5
STORY:
The Unified UX needs reusable primitive components that work across
Social, Swarm, and Graph views. These build on shadcn/ui foundation
with consistent styling and behavior.
COLLABORATION:
Created shared primitives:
- BaseCard: Wraps shadcn Card with consistent padding, hover states,
and selection styling
- AgentAvatar: Avatar with liveness glow indicator (active/stale/stuck/dead)
- StatusBadge: Status display with consistent styling
These components use the earthy-dark tokens and are designed for
composability across all three views (Social, Graph, Swarm).
DELIVERABLES:
- src/components/shared/base-card.tsx
- src/components/shared/agent-avatar.tsx
- src/components/shared/status-badge.tsx
- src/components/shared/index.ts (barrel export)
- Tests in tests/components/shared/
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
- npm run test: PASS
CLOSES: bb-ui2.3
BLOCKS: bb-ui2.5, bb-ui2.11, bb-ui2.16
STORY:
The Unified UX epic needed a solid component foundation. We chose
shadcn/ui for its Tailwind integration and copy-paste philosophy.
COLLABORATION:
Initialized shadcn/ui with Next.js defaults and installed the base
component set needed for the unified shell:
- button: Primary actions
- card: Card containers
- badge: Status badges
- avatar: Agent avatars
- input: Search/filter inputs
- scroll-area: Scrollable containers
- separator: Visual dividers
- tooltip: Hover information
- dropdown-menu: Sorting and filtering
We also updated tsconfig.json with path aliases (@/*) to support
the shadcn import pattern.
DELIVERABLES:
- components.json configuration
- 9 shadcn components in components/ui/
- lib/utils.ts with cn() helper
- tsconfig.json with @/* path aliases
VERIFICATION:
- npm run typecheck: PASS
- npm run lint: PASS
CLOSES: bb-ui2.2
BLOCKS: bb-ui2.3, bb-ui2.5
STORY:
In a multi-agent control center, operators need to quickly identify
what TYPE of agent they're looking at - UI agents, graph agents,
orchestrators, or general workers.
COLLABORATION:
We implemented role-based border colors on agent avatars:
- ui agents: blue border
- graph agents: green border
- orchestrators: purple border
- default/other: gray border
The agent-station component now displays these colors, making it
instantly visible what role each agent plays in the swarm.
DELIVERABLES:
- AgentStation component with role-based styling
- agent-station-logic.ts with role color derivation
- Tests: agent-station-logic.test.ts updated and passing
VERIFICATION:
- typecheck: PASS
- lint: PASS
- test: PASS
CLOSES: bb-buff.3.4
STORY:
The Sessions Hub needs to show which task each agent is working on,
creating a visual "mission link" between agents and their active work.
COLLABORATION:
We implemented the data layer for mission pathing:
- getAgentActiveMissions() returns tasks owned by an agent
- getActiveMissionCount() for badge indicators
- getMissionsByAgent() groups all missions for batch rendering
DELIVERABLES:
- src/lib/agent-sessions.ts extended with mission functions
- Tests: 8/8 PASS in tests/lib/mission-pathing.test.ts
STATUS: in_progress (visual rendering layer still pending)
Visual path lines would require SVG overlay + position tracking.
CLOSES: partial bb-buff.3.3
STORY:
The Sessions Hub needed clear visual distinction between healthy
agents and those in trouble. Users couldn't quickly identify stuck
or dead agents in the control center view.
COLLABORATION:
We added 'stuck' and 'dead' states to the AgentSessionState type,
created deriveSessionState() with Zero-Failure-Check priority,
and implemented restrained visual treatments:
- stuck: pulsing red border (ring-2 ring-red-500 animate-pulse)
- dead: strong ghosting (opacity-40 grayscale)
- evicted: milder ghosting (opacity-60 grayscale-[0.5])
Session cards now display STUCK/OFFLINE badges with aria-labels
for accessibility.
DELIVERABLES:
- AgentSessionState extended with stuck/dead states
- deriveSessionState() derives from ZFC state priority
- Visual treatments for stuck/dead/evicted
- Accessible badges with aria-label
TESTS:
- tests/lib/agent-sessions-state.test.ts: 6/6 PASS
- tests/components/shared/status-utils-visual.test.ts: 4/4 PASS
- tests/components/sessions/session-feed-card-state.test.tsx: 4/4 PASS
CLOSES: bb-buff.3.2
BLOCKS: bb-buff.3.3
STORY:
The session backend needed to aggregate agent health from a live
telemetry stream rather than static bead metadata. This refactor
makes liveness signals real-time and accurate.
COLLABORATION:
We extended the ActivityEvent model with a native 'heartbeat' kind,
updated extendActivityLease() to emit through the activity bus, and
refactored getAgentLivenessMap() to prioritize heartbeat activity
history over stale bead metadata.
DELIVERABLES:
- ActivityEvent extended with 'heartbeat' kind
- extendActivityLease() emits heartbeats through activity bus
- getAgentLivenessMap() prefers telemetry over static metadata
- Registry APIs support projectRoot injection for testing
- Tests verify preference logic via TDD
VERIFICATION:
- 93/93 tests PASSING
- Heartbeat override verified in isolated temp projects
CLOSES: bb-buff.1.3
BLOCKS: bb-buff.3.2, bb-buff.3.3, bb-buff.2.1
Research revealed that agent identities (consolidated to bd beads) were appearing in standard task lists because the data-access layer lacked identity-awareness.
- Refactored read-issues.ts and parser.ts to explicitly exclude beads labeled 'gt:agent' from standard mission flows.
- Verified that agent personas remain targetable by the registry but are invisible to Kanban/Graph/Sessions.
- Added Characterization Test: identity-isolation.test.ts.
This restores the 'War Room' clarity by separating Operatives from Missions.
OPERATIVE: silver-castle
SESSION: 2026-02-14-1630
We've transformed the Social-Dense Hub into a high-fidelity operational surface.
- BACKEND: Implemented Global Incursion Engine in agent-sessions.ts (N^2 overlap detection) and added the 60m 'Idle' state.
- API: Enriched the sessions payload with full metadata and active conflict arrays.
- HEADER: Delivered 4-state agent stations (Active/Stale/Evicted/Idle) with real-time 'time-ago' timers.
- FEED: Implemented the 'Fire Map' visuals:
* Global Incursion Ticker: High-visibility alerts for agent collisions.
* Local Conflict Badges: Pulsing pills on affected task cards.
- Refactored components for React-static compliance and strict TypeScript safety.
This commit completes the visibility track, allowing the human supervisor to monitor agent presence and friction in real-time.
OPERATIVE: silver-castle
SESSION: 2026-02-14-1430
Following a critical collaboration to resolve Windows terminal pop-ups, we've delivered a more robust 'Passive Activity' architecture:
- Terminology Pivot: Renamed 'Heartbeat' to 'Activity Lease' (Parking Permit model).
- Side-Effect Extension: tools/bb.ts now automatically extends the agent's lease whenever they perform real work (any CLI command).
- Passive Handshake: bb-init.mjs now only performs an initial registration/lease start, with no background loops.
- 100% Silence: Removed all background process spawning, ensuring zero terminal disruption on Windows.
- High Observability: Liveness is still tracked via the 15m threshold, but relies on activity rather than periodic pings.
OPERATIVE: silver-castle
SESSION: 2026-02-14-1330
The previous background loop approach was disruptive on Windows (terminal pop-ups).
We collaborated to find a more robust, silent alternative:
- Removed all background heartbeat worker logic and PID management.
- Implemented 'Passive Heartbeat' in tools/bb.ts: every agent command now refreshes liveness as a side-effect.
- Updated bb-init.mjs to use explicit heartbeat calls for adoption/registration.
- Result is 100% silent observability: if an agent is working, they are Active. If they stop, they drift to Stale.
OPERATIVE: silver-castle
SESSION: 2026-02-14-1300
Finalizing the backend engine for the Operative Protocol.
- Updated agent-sessions.ts to use the deriveLiveness logic and the 15m protocol threshold.
- Integrated the agentLivenessMap into the session aggregation to provide real-time status in the Hub.
- Updated the GET /api/sessions endpoint to fetch and serve liveness metadata.
- Fixed linting warnings (unused imports) in reservations, sessions, and test files.
This commit completes the backend contract for bb-u6f.6.2, providing the data layer necessary for the upcoming 'War Room' UI enhancements.
OPERATIVE: silver-castle
SESSION: 2026-02-14-1145
Our collaboration led to a rigorous 'Session Constitution' where we prioritized observability and concurrency safety.
I've delivered the first four pillars of the backend engine:
1. Liveness Registry: Heartbeat logic and derivation of active/stale/evicted states based on the 15m threshold.
2. Overlap Classifier: Canonical path normalization (Windows-aware) and exact/partial overlap detection.
3. Takeover Rules: Enforced discipline where active agents are protected, while stale/evicted ones can be overtaken via --takeover-stale.
4. Protocol Schema: Establishing the v1 envelope for high-fidelity agent signaling.
TDD was applied throughout, with 100% pass rate on the new liveness, overlap, takeover, and protocol tests.
- Fix isValidProjectRoot() in 4 API routes to properly prevent path traversal
by using path.relative() to ensure paths stay within allowed base directory
(replaces ineffective normalized.includes('..') check)
- Fix readiness-report.mjs to remove misleading path traversal validation
that was ineffective after path.resolve() removes '..' segments
- Fix asNonEmptyString() in mutations.ts to only remove control characters
while preserving backslashes (for Windows paths) and punctuation (for user text)
These changes address security review comments about ineffective path traversal
checks and mutation input corruption.
The original implementation used fs.flock() which is not available in the
Node.js fs/promises API. Replaced with a portable file-based mutex using
exclusive file creation (flag: 'wx') with retry logic.
This ensures the race condition fix for agent reservations works correctly
across all Node.js versions and platforms.
Critical fixes:
- Fix duplicated isPolling/pollLastTouched in events route (missing closing brace)
- Add missing path import to realtime.ts (path.basename was used without import)
- Fix error.message leak in sessions and beads/read routes (security)
- Add missing NextResponse import to activity route
- Fix diffDependencies to use composite key (type:target) for accurate tracking
Code quality:
- Fix beadCounts computation in kanban-controls (was counting epic's own deps, not child issues)
- Replace require('path') with ES module imports throughout
Tests: 13/15 passing (2 contract tests remain brittle)
Co-authored-by: openhands <openhands@all-hands.dev>
This reverts commit 3b692e894c.
The Qodo bot incorrectly unescaped Unicode characters in the JSON:
- \u003c (Unicode for <) was changed to <
- \u001b (Unicode for ESC) was changed to event
This broke the JSON structure and validity.
Added a comprehensive code quality agent named 'Code Custodian' that identifies and fixes issues in the codebase, including test coverage, linting, documentation, and deprecated API usage.
- Add missing snapshot-differ.test.ts to npm test script
- Fix path traversal vulnerability in agent-mail.ts with message ID validation
- Fix readLastTouchedVersion to log errors instead of silently swallowing them
- Sanitize log statements to not leak full paths
- Add projectRoot validation to all API routes
- Fix activity persistence write race conditions with promise chaining
Co-authored-by: openhands <openhands@all-hands.dev>
We moved from ad-hoc task claims to a strictly defined 'Skill' system.
Triumphs:
- Implemented the 'beadboard-driver' skill, which encodes our project-specific coordination protocols (claim, reservation, handoff).
- This ensures that any AI operative (or human supervisor) can participate in the project lifecycle using a unified CLI-driven state machine.
- Decoupled high-level mission logic from low-level file mutations, allowing for easier agent skill composition in the future.
Raw Honest Moment:
Initially, we were just 'winging it' with manual status updates. Formalizing this into a skill was a necessary step to ensure our collaboration is repeatable and resilient to agent context swaps.
We completed the 'Deep Metadata Etch' today, transforming our Beads issues from simple trackers into a permanent narrative of our collaboration.
Triumphs:
- Exhaustively updated all epic and sub-task descriptions with technical implementation reports and 'Execution Tales'.
- Finalized the 'bb' agent CLI skill (bb.ps1), providing a reliable, path-safe interface for cross-agent communication.
- Published ADR-001 and RFC-001 to document our coordination protocols.
- Fixed the 'missing closed issues' bug across all pages by enforcing --all and --limit 0 in read-issues.ts.
Raw Honest Moment:
We realized our 'Memory Bank' was initially too shallow. We went back and re-wrote descriptions for over 15 beads to ensure that future AI agents (and human maintainers) understand not just *what* we built, but *why* we chose specific architectural trade-offs. This commit represents our commitment to documentation as a first-class citizen of engineering.
We added the third major surface to the BeadBoard workspace: the Chronological Timeline. This provides the 'Audit' layer of our operational hierarchy.
Triumphs:
- Built the /timeline route with sticky date grouping and polymorphic EventCards.
- Integrated the ActivityPersistence library to bridge the gap between ephemeral SSE events and persistent project history.
- Implemented real-time Agent Stats endpoints (/api/agents/[id]/stats) that derive throughput and 'Wins' from the project stream.
Raw Honest Moment:
We almost shipped this without persistence, which would have meant the project history would disappear every time the server restarted. Realizing that 'Observability' requires 'Survivability' led us to build the .beadboard/activity.json buffer, a small but vital piece of engineering that makes the timeline actually useful.
