Skip to content

gt doctor --fix fails to create agent and rig beads due to invalid issue type validation #1002

@rschnitz

Description

@rschnitz

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: agent

Via 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 error

Expected 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:

  1. bd create --help explicitly documents these types:

    -t, --type string  Issue type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event)
    
  2. 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)
  3. However, validation rejects agent, role, rig, convoy, event, gate, and merge-request as 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:

  1. Incomplete implementation - Types were added to CLI but validation wasn't updated
  2. Feature flag - Types exist but are gated behind a config/flag
  3. Version mismatch - Help docs updated but validation in older code path
  4. 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 create command - 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 doctor checks:
    • agent-beads-exist - Expects to create type=agent beads
    • rig-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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions