-
Notifications
You must be signed in to change notification settings - Fork 1k
Description
Bug Report: gt doctor --fix fails to create agent and rig beads due to invalid issue type validation
Date: 2026-01-10T12:31:14-08:00
Reporter: rschnitz
Summary
This is a Beads bug. The bd create --help documentation explicitly lists agent, role, rig, convoy, event, gate, and merge-request as supported issue types, and even provides type-specific flags (e.g., --agent-rig, --role-type). However, validation logic rejects these types with "invalid issue type" errors.
This was discovered when gt doctor --fix attempted to create agent and rig identity beads, but the issue can be reproduced directly with bd create --type=agent.
Steps to Reproduce
Direct reproduction (beads only):
# Check that bd create help documents agent type support
bd create --help | grep "type string"
# Output: -t, --type string Issue type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event)
# Try to create an issue with type=agent
bd create --type=agent --title="Test agent" --role-type=polecat
# Error: validation failed: invalid issue type: agentVia gt doctor (original discovery path):
# 1. Run gt doctor to identify health issues
gt doctor
# Output shows:
# ✗ agent-beads-exist: 2 agent bead(s) missing
# hq-deacon
# hq-mayor
# ✗ rig-beads-exist: 1 rig identity bead(s) missing
# le-rig-LexiconBlocks
# 2. Attempt auto-fix
gt doctor --fix
# Fails with same validation errorExpected Behavior
Since bd create --help documents agent, role, rig, convoy, event, gate, and merge-request as valid types, and provides type-specific flags like --agent-rig and --role-type, these types should be accepted by validation and issues should be created successfully.
Actual Behavior
✗ agent-beads-exist: 2 agent bead(s) missing
hq-deacon
hq-mayor
Fix failed: creating hq-deacon: bd create --json --id=hq-deacon --type=agent --title=Deacon (daemon beacon) - receives mechanical heartbeats, runs town plugins and monitoring. --description=Deacon (daemon beacon) - receives mechanical heartbeats, runs town plugins and monitoring.
role_type: deacon
rig: null
agent_state: idle
hook_bead: null
role_bead: hq-deacon-role
cleanup_status: null
active_mr: null
notification_level: null: Error: validation failed: invalid issue type: agent
→ Run 'gt doctor --fix' to create missing agent beads
✗ rig-beads-exist: 1 rig identity bead(s) missing
le-rig-LexiconBlocks
Fix failed: creating le-rig-LexiconBlocks: bd create --json --id=le-rig-LexiconBlocks --type=rig --title=LexiconBlocks --description=Rig identity bead for LexiconBlocks.
repo: https://github.com/AutoGenOnline/LexiconBlocks.git
prefix: le
state: active: Error: validation failed: invalid issue type: rig
→ Run 'gt doctor --fix' to create missing rig identity beads
Analysis
Root Cause: Beads' CLI help documentation and validation logic are out of sync.
Evidence:
-
bd create --helpexplicitly documents these types:-t, --type string Issue type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event) -
Help includes flags specific to these types:
--agent-rig string(requires --type=agent)--role-type string(requires --type=agent)--event-actor,--event-category,--event-payload,--event-target(requires --type=event)--waits-for,--waits-for-gate(requires --type=gate)
-
However, validation rejects
agent,role,rig,convoy,event,gate, andmerge-requestas invalid types
Impact:
- Documented features are unusable
- gt (a consumer of beads) cannot create required identity beads
- gt doctor always reports agent/rig beads as missing
- Users following the documented API receive errors
Possible Root Causes:
- Incomplete implementation - Types were added to CLI but validation wasn't updated
- Feature flag - Types exist but are gated behind a config/flag
- Version mismatch - Help docs updated but validation in older code path
- Regression - Validation was accidentally restricted in a recent change
Environment
bd: bd version 0.46.0 (dev)
gt: gt version 0.2.3 (dev)
OS: Darwin 25.1.0
Shell: /bin/zsh
GT_ROOT: not set
PWD: ~/gt
Diagnostic Output
Click to expand bd doctor output
bd doctor v0.46.0
CORE SYSTEM
✓ Installation .beads/ directory found
✓ Fresh Clone Database exists
✓ Database version 0.46.0
└─ Storage: SQLite
✓ Schema Compatibility All required tables and columns present
✓ Repo Fingerprint Verified (8bb5246b)
✓ Database Integrity No corruption detected
✓ Issue IDs hash-based ✓
✓ CLI Version 0.46.0 (latest)
✓ Permissions All permissions OK
DATA & CONFIG
✓ Database Files Single database file
⚠ JSONL Files Multiple JSONL files found: issues.jsonl, routes.jsonl
└─ Having multiple JSONL files can cause sync and merge conflicts.
Only one JSONL file should be used per repository.
✓ JSONL Config Using issues.jsonl
✓ Database Config Configuration matches existing files
✓ Config Values All configuration values are valid
✓ JSONL Integrity issues.jsonl looks valid
⚠ DB-JSONL Sync Status mismatch: 6 issue(s) have different status in DB vs JSONL
└─ Status mismatches detected:
hq-jr0: DB=closed, JSONL=open
hq-n9c: DB=closed, JSONL=open
hq-jxg: DB=closed, JSONL=open
... and 3 more
✖ Sync Divergence 2 sync divergence issue(s) detected
└─ Database import time is newer than JSONL (2026-01-10T12:29:54-08:00 > 2026-01-10T12:05:48-08:00)
Uncommitted .beads/ changes (1 file(s))
✓ Untracked Files All .beads/*.jsonl files are tracked
GIT INTEGRATION
✓ Git Hooks All recommended hooks installed
└─ Installed: pre-commit, post-merge, pre-push
✓ Sync Branch Hook Compatibility N/A (sync-branch not configured)
✓ Gitignore Up to date
✓ Issues Tracking issues.jsonl is tracked by git
✓ Redirect Tracking No redirect file present
✓ Git Merge Driver Correctly configured
└─ bd merge %A %O %A %B
⚠ Git Working Tree Uncommitted changes present
└─ ?? .beads/
?? .claude/
?? .events.jsonl
?? .feed.jsonl
?? .gitattributes
?? .gitignore
?? AGENTS.md
?? LexiconBlocks/
…
⚠ Git Upstream No upstream configured for master
✓ Sync Branch Config N/A (no remote configured)
✓ Sync Branch Health N/A (no sync branch configured)
✓ Orphaned Issues No issues referenced in commits but still open
✓ Sync Branch Gitignore N/A (sync.branch not configured)
RUNTIME
✓ Git Sync Setup Git repository detected (sync-branch not configured)
└─ Beads commits directly to current branch. For team collaboration or to keep beads changes isolated, consider using a sync-branch.
✓ Daemon Health Daemon running (PID 34279, version 0.46.0)
✓ Daemon Auto-Sync No sync-branch configured (auto-sync not applicable)
✓ Daemon Config Using current config format
INTEGRATIONS
⚠ Claude Plugin version 0.30.0 (latest: 0.46.0)
✓ Claude Integration Plugin installed
└─ Slash commands and workflow hooks enabled via plugin
✓ Gemini CLI Integration Not configured
└─ Run 'bd setup gemini' to enable Gemini CLI integration
✓ CLI Availability 'bd' command available in PATH
✓ Prime Documentation No bd prime references in documentation
✓ Agent Documentation Documentation found: AGENTS.md
METADATA
✓ Dependency Cycles No circular dependencies detected
✓ Legacy Commands No legacy beads slash commands detected
✓ Version Tracking Version tracking active (version: 0.46.0)
✓ Deletions Manifest Using inline tombstones
✓ Tombstones None (no deleted issues)
✓ Child-Parent Dependencies No child→parent dependencies
MAINTENANCE
✓ Stale Closed Issues No stale closed issues
✓ Stale Molecules No stale molecules
✓ Persistent Mol Issues No persistent mol- issues
✓ Expired Tombstones No expired tombstones
✓ Compaction Candidates No compaction candidates
✓ Pending Migrations None required
OTHER
✓ Merge Artifacts No merge artifacts found
✓ Orphaned Dependencies No orphaned dependencies
⚠ Duplicate Issues 1 duplicate issue(s) in 1 group(s)
└─ Duplicates cannot be auto-fixed
✓ Test Pollution No test pollution detected
✓ Git Conflicts No git conflicts in JSONL
✓ Large Database 6 closed issues (threshold: 5000)
──────────────────────────────────────────
✓ 51 passed ⚠ 6 warnings ✖ 1 failed
⚠ WARNINGS
✖ 1. Sync Divergence: 2 sync divergence issue(s) detected
└─ bd export OR bd sync
⚠ 2. JSONL Files: Multiple JSONL files found: issues.jsonl, routes.jsonl
└─ Determine which file is current and remove the others:
1. Check .beads/metadata.json for 'jsonl_export' setting
2. Verify with 'git log .beads/*.jsonl' to see commit history
3. Remove the unused file(s): git rm .beads/<unused>.jsonl
4. Commit the change
⚠ 3. DB-JSONL Sync: Status mismatch: 6 issue(s) have different status in DB vs JSONL
└─ Run 'bd export -o issues.jsonl' to update JSONL from DB (DB is usually source of truth)
⚠ 4. Git Working Tree: Uncommitted changes present
└─ Commit or stash changes, then follow AGENTS.md: git pull --rebase && git push
⚠ 5. Git Upstream: No upstream configured for master
└─ Set upstream then push: git push -u origin master
⚠ 6. Claude Plugin: version 0.30.0 (latest: 0.46.0)
└─ Update plugin: /plugin update beads@beads-marketplace
Restart Claude Code after update
⚠ 7. Duplicate Issues: 1 duplicate issue(s) in 1 group(s)
└─ Run 'bd duplicates' to review and merge duplicates
bd doctor failed
Click to expand gt doctor output
✓ town-config-exists: mayor/town.json exists
✓ town-config-valid: mayor/town.json valid (name=gt, version=2)
✓ rigs-registry-exists: mayor/rigs.json exists
✓ rigs-registry-valid: All 1 registered rig(s) exist
✓ mayor-exists: mayor/ directory exists with required files
⚠ global-state: Global state not initialized
→ Run: gt enable
✓ town-git: Town root is under version control
✓ daemon: Daemon is running (PID 8564)
✓ repo-fingerprint: Repository fingerprints verified
✓ boot-health: Boot watchdog healthy
✓ beads-database: No issues.db file (will be created on first use)
✓ formulas: 25 formulas up-to-date
✓ bd-daemon: bd daemon is running and healthy
✓ prefix-conflict: No prefix conflicts found
✓ prefix-mismatch: No prefix mismatches found
✓ routes-config: Routes configured correctly (1 routes)
✓ orphan-sessions: All 1 Gas Town sessions are valid
⚠ orphan-processes: Found 2 runtime process(es) running outside tmux
These may be your personal sessions or orphaned Gas Town processes.
Verify these are expected before manually killing any:
PID 54971: claude (parent: 73036)
PID 43733: claude (parent: 4282)
⚠ gt-root-env: 1 session(s) missing GT_ROOT environment variable
Missing GT_ROOT: gt-LexiconBlocks-witness
Sessions without GT_ROOT cannot find town-level formulas.
→ Restart sessions to pick up GT_ROOT: gt shutdown && gt up
✓ wisp-gc: No abandoned wisps found
✓ persistent-role-branches: All 2 persistent roles on main branch
✓ beads-sync-orphans: No beads-sync branch (single-clone setup)
✓ clone-divergence: All 3 clones in sync with origin/main
✓ identity-collision: no worker locks found
✓ linked-panes: Not enough sessions to check for linking
✓ themes: 1 session(s) have correct themes
✓ patrol-molecules-exist: All 1 rig(s) have patrol molecules
✓ patrol-hooks-wired: Daemon configured with 3 patrol(s)
✓ patrol-not-stuck: No stuck patrol wisps found
✓ patrol-plugins-accessible: All plugin directories accessible
✓ patrol-roles-have-prompts: All patrol role prompt templates found
✓ agent-beads-exist: All 5 agent beads exist
✗ rig-beads-exist: 1 rig identity bead(s) missing
le-rig-LexiconBlocks
→ Run 'gt doctor --fix' to create missing rig identity beads
✓ rig-settings: All 1 rig(s) have settings/ directory
✓ session-hooks: All 2 settings.json file(s) use proper session_id passthrough
✓ runtime-gitignore: .runtime/ properly gitignored
✓ legacy-gastown: No legacy .gastown/ directories found
✓ claude-settings: All Claude settings.json files are up to date
✓ crew-state: All 1 crew state files valid
✓ crew-worktrees: No cross-rig worktrees in crew directories
✓ commands-provisioned: Town-level slash commands provisioned (handoff.md)
✓ lifecycle-hygiene: No stale lifecycle messages found
✓ hook-attachment-valid: All hook attachments are valid
✓ hook-singleton: All handoff beads are unique
✓ orphaned-attachments: No orphaned handoff beads found
45 checks, 41 passed, 3 warnings, 1 errors
Error: doctor found 1 error(s)
Usage:
gt doctor [flags]
Flags:
--fix Attempt to automatically fix issues
-h, --help help for doctor
--restart-sessions Restart patrol sessions when fixing stale settings (use with --fix)
--rig string Check specific rig only
-v, --verbose Show detailed output
gt doctor failed
Relevant Files/Code
Beads (primary issue):
bd createcommand - CLI accepts documented types in help but validation rejects them- Issue type validation logic - Rejects
agent,role,rig,convoy,event,gate,merge-request - Help documentation - Documents these types as valid (see
bd create --help) - Type-specific flags implementation:
--agent-rig,--role-type(agent-specific)--event-actor,--event-category, etc. (event-specific)--waits-for,--waits-for-gate(gate-specific)
Gas Town (affected consumer):
gt doctorchecks:agent-beads-exist- Expects to create type=agent beadsrig-beads-exist- Expects to create type=rig beads
gt/mayor/rigs.json- Registry of rigs requiring identity beads
Submit to: Beads Issues
https://github.com/steveyegge/beads/issues/new
This is a beads bug where documented issue types are rejected by validation. While discovered via gt doctor --fix, the issue can be reproduced directly with bd create --type=agent independent of Gas Town.
This bug report was generated using rschnitz's /bugreport command (gt-bd-bugreport)
20260110-123114-gt-doctor---fix-fails-to-create-agent-and-rig-bead.md