Bead archival â clean up old beads without deleting

[jrf0110]

Parent

Part of #204 (Phase 4: Hardening)

Problem

Old beads (completed work, failed attempts, resolved escalations) accumulate on the bead board and in query results. The only way to clean them up is to delete them, which destroys the work history permanently. Users want to declutter the active view without losing the record of what was done.

Solution

Add an archived status (or an archived_at timestamp flag) to beads. Archived beads are hidden from default views but remain in the database for history, audit, and search.

Bead lifecycle with archival

open â in_progress â closed â archived
                   â failed  â archived

Archival is a terminal operation on beads that are already in a terminal state (closed or failed). Open and in-progress beads cannot be archived.

Implementation

Schema: Add archived_at TEXT column to the beads table. A non-null value means the bead is archived.

Default query behavior: All existing bead queries (listBeads, gt_list_beads, bead board, convoy status) should exclude archived beads by default. Add a WHERE archived_at IS NULL predicate to default queries and an include_archived: boolean parameter for explicit inclusion.

Archive operations:

• Archive a single bead: set archived_at = now()
• Archive all closed beads in a rig: bulk operation
• Archive all beads in a closed convoy: single action that archives the convoy bead and all tracked beads
• Unarchive: set archived_at = NULL (in case of mistakes)

UI:

• Bead board: archived beads hidden by default. Toggle "Show archived" to include them (greyed out).
• Bead detail panel: "Archive" button on closed/failed beads. "Unarchive" button on archived beads.
• Bulk action: "Archive all closed beads" button on rig view.

Mayor tools:

• Extend gt_bead_update (from Mayor edit capabilities + manual bead/agent/convoy editing #996) to support archiving
• Or add a dedicated gt_archive_beads tool that accepts filters (e.g., "archive all closed beads older than 7 days")

Acceptance Criteria

• archived_at column added to beads table
• Archived beads hidden from default bead list, bead board, and Mayor tool results
• Archive/unarchive operations available via HTTP API, Mayor tool, and dashboard UI
• Bulk archive: all closed beads in a rig, all beads in a closed convoy
• Archived beads still queryable with explicit include_archived flag
• Bead events logged for archive/unarchive operations

Notes

• No data migration needed
• Using archived_at timestamp rather than a status enum value keeps the status field clean (still represents the work lifecycle) and allows querying "when was this archived?"
• Agent GC in patrol.ts already handles dead agents. This is the bead equivalent Ã�Ã�¢ manual/semi-automatic cleanup of completed work.
• Consider auto-archival: beads closed for >30 days could be auto-archived by the alarm loop. This is a stretch goal.