agent-beads-exist Unfixable

[elmpp]

Bug Description

Doctor reports 3 missing agent beads. Unfixable through doctor

Steps to Reproduce

Clean setup:

gt install ~/gt --git

gt rig add langra http://192.168.4.99:3012/matt/langra.git
# set up the config/settings.json and the langra/settings/config.json
gt crew add matt --rig langra
gt crew at langra/matt

Expected Behavior

No doctor issues

Actual Behavior

Environment

• OS: MacOS 15.6.1
• Go version: go version go1.25.5 darwin/arm64
• Gas Town version: $ gt info
  Gas Town v0.12.1 (Homebrew)
  v0.12.1@Homebrew

Logs / Error Output

 17:01:27 ~/gt
$ gt doctor --fix

  ✓  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 healthy
  ✓  stale-binary Cannot locate gt source repo (not a development environment)
  ✓  beads-binary bd 0.61.0
  ✓  dolt-binary dolt 1.83.6
  ✓  dolt-server-reachable Dolt server reachable (2 rig(s) in server mode)
  ✓  town-git Town root is under version control
  ✓  town-root-branch Town root is on main branch
  ✓  foreign-remotes No extra remotes configured
  ✓  branch-protection Branch protection installed in post-checkout hook
  ✓  claude-settings All Claude settings.json files are up to date
  ✓  daemon Daemon is running (PID 87801)
  ✓  tmux-global-env GT_TOWN_ROOT=/Users/matt/gt in tmux global env
  ✓  boot-health Boot watchdog healthy
  ✓  town-beads-config Town beads config.yaml present
  ✓  beads-custom-types All custom types registered
  ✓  beads-custom-statuses All custom statuses registered
  ✓  formulas 42 formulas up-to-date
  ✓  prefix-conflict No prefix conflicts found
  ✓  rig-name-mismatch No rig specified (skipped)
  ✓  rig-config-sync All registered rigs have valid configuration
  ✓  stale-dolt-port All Dolt port files are consistent
  ✓  prefix-mismatch No prefix mismatches found
  ✓  database-prefix All database prefixes match routes.jsonl
  ✓  idle-timeout-config All 1 rigs have dolt.idle-timeout set to "0"
  ✓  routes-config Routes configured correctly (3 routes)
  ✓  rig-routes-jsonl No rig-level routes.jsonl files (1 rigs checked)
  ✓  routing-mode Beads routing.mode is explicit
  ✓  session-name-format All Gas Town sessions use current naming format
  ✓  orphan-sessions All 7 Gas Town sessions are valid
  ⚠  zombie-sessions Found 1 zombie session(s) (fixing)...
  ✓  orphan-processes No runtime processes found
  ✓  wisp-gc No abandoned wisps found
  ✓  misclassified-wisps No misplaced ephemerals found
  ✓  jsonl-bloat issues.jsonl not bloated
  ✓  stale-beads-redirect No stale beads files or redirect issues found
  ✓  beads-redirect-target All beads redirect targets are valid
  🔧 stale-runtime-files No stale runtime files found (fixed)
  ✓  persistent-role-branches All 1 persistent roles on main branch
  ✓  clone-divergence All 3 clones in sync with origin/main
  ✓  default-branch-all-rigs All 1 rig(s) with custom default_branch validated
  ✓  identity-collision 1 worker lock(s), all healthy
  ✓  linked-panes All 2 Gas Town sessions have independent panes
  ✓  socket-split-brain Town socket is default — no split-brain possible
  ✓  themes 2 session(s) have correct themes
  ✓  crash-reports No recent crash reports found
  ✓  env-vars All 2 session(s) have correct environment variables
  ✓  patrol-molecules-exist All 1 rig(s) have patrol formulas accessible
  ✓  patrol-hooks-wired Daemon configured with 10 patrol(s)
  ✓  patrol-not-stuck No stuck patrol wisps found
  ✓  patrol-plugins-accessible All plugin directories accessible
  ✓  patrol-plugin-drift Plugin source not found (skipping drift check)
  ✖  agent-beads-exist 3 agent bead(s) missing (fixing)...
  ✓  stale-agent-beads No stale agent beads found
  ✓  rig-beads-exist All 1 rig identity beads exist
  ✓  role-config-valid Role config uses built-in defaults
  ✓  rig-settings All 2 rig(s) have settings/ directory
  ✓  session-hooks All 7 settings.json file(s) use proper session_id passthrough
  ✓  runtime-gitignore .runtime/ properly gitignored
  ✓  legacy-gastown No legacy .gastown/ directories found
  ✓  deprecated-merge-queue-keys No deprecated merge_queue keys in 2 rig(s)
  ✓  land-worktree-gitignore .land-worktree/ gitignored in 2 rig(s)
  ✓  hooks-path-all-rigs All 0 clone(s) have hooks configured
  ✓  sparse-checkout No legacy sparse checkout configurations found
  ✓  priming Priming subsystem is correctly configured
  ✓  town-claude-md Town-root CLAUDE.md has all required sections
  ✓  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, review)
  ✓  lifecycle-hygiene No stale lifecycle messages found
  ✓  lifecycle-defaults All lifecycle patrols configured
  ✓  hook-attachment-valid All hook attachments are valid
  ✓  hook-singleton All handoff beads are unique
  ✓  orphaned-attachments No orphaned handoff beads found
  ✓  stale-task-dispatch No stale task-dispatch hooks found
  ✓  hooks-sync All 7 hook targets in sync
  ✓  dolt-metadata All 1 rig(s) have Dolt server metadata
  ✓  dolt-orphaned-databases No orphaned databases in .dolt-data/
  ✓  unregistered-beads-dirs No unregistered beads directories found
  ✓  null-assignee-steps No in_progress beads with NULL assignee found
  ✓  worktree-gitdir-valid All worktree gitdir references are valid
──────────────────────────────────────────
✓ 83 passed  ⚠ 1 warnings  ✖ 1 failed  🔧 1 fixed

✖  FAILURES
  ✖  1. agent-beads-exist: 3 agent bead(s) missing
        └─ Run 'gt doctor --fix' to create missing agent beads

⚠  WARNINGS
  ⚠  1. zombie-sessions: Found 1 zombie session(s)
        └─ Run 'gt doctor --fix' to kill zombie sessions

🔧  FIXED
  ✓  1. stale-runtime-files: No stale runtime files found (fixed)
Error: doctor found 1 error(s)
Usage:
  gt doctor [flags]

Flags:
      --fix                  Attempt to automatically fix issues
  -h, --help                 help for doctor
      --no-start             Suppress starting daemon/agents during --fix
      --restart-sessions     Restart patrol sessions when fixing stale settings (use with --fix)
      --rig string           Check specific rig only
      --slow string[="1s"]   Highlight slow checks (optional threshold, default 1s)
  -v, --verbose              Show detailed output

Additional Context

[DreadPirateRobertz]

The agent-beads-exist check failing on a new install with gt rig add is likely because no polecats have been spawned yet — there are no agent beads to find, by design. gt doctor --fix shouldn't create agent beads speculatively.

The check should be gated: skip agent-beads-exist if no polecats have ever run in the rig (no evidence of past agent activity). A simple heuristic: if bd list --type=agent returns empty AND the witness log shows no completed polecat sessions, suppress the check as 'not applicable for fresh rigs'.

[DreadPirateRobertz]

The agent-beads-exist doctor check verifies that beads records exist for each agent. When you add a crew member via gt crew add, agent beads may not be auto-created for a fresh rig — this is a known gap where doctor detects the missing records but doesn't have a fix path.

Workaround: run bd init --prefix <rig-prefix> on the rig, or if beads already exists, try gt doctor --fix after confirming which bead IDs are expected. If --fix doesn't resolve it, the identity beads may need to be created manually via bd create with the correct agent identity labels.

Could you share the exact doctor output (the 3 missing bead IDs it reports)? That would help narrow down whether this is a rig-init ordering issue or a bug in the crew-add flow.

[DreadPirateRobertz]

This is the same routing issue as #3087 — gt doctor --fix cannot create agent beads for rigs backed by a remote Dolt server when the rig uses a routed prefix.

In your case, the langra rig has an la- prefix (or similar) routed via routes.jsonl to the Dolt server at 192.168.4.99:3012. The bd create --id=la-matt call from the doctor fix path cannot resolve that route.

Short-term workaround: manually create the missing agent beads with direct bd calls that specify the correct database:

# List the missing beads to identify their IDs
gt doctor 2>&1 | grep "missing"

# For each missing bead, create it directly using --server:
bd create --id=la-matt-witness --title="witness" --type=agent --labels=gt:agent --ephemeral --force --server

Run from the langra rig directory — bd will use the routes.jsonl config and find the correct Dolt server automatically.

Root fix: see #3087 for the tracked fix. The gt doctor --fix path needs to follow routes.jsonl when calling bd create for routed prefixes, or verify the bead was created after the call.

[Bella-Giraffety]

PR #3471 is the narrow fix for this specific scoped-doctor failure. It only prevents route-derived agent expectations from leaking in from unrelated rigs during runs, without broadening into the rest of the doctor stack.

[Bella-Giraffety]

PR #3471 is the narrow fix for this specific scoped doctor failure. It keeps route-derived agent-bead expectations from leaking in from unrelated rigs during scoped doctor runs, without broadening into the rest of the doctor stack.