fix(gt-4ly): use bd set-state for agent state + read from labels

Replace the removed `bd agent state` call with `bd set-state`, which
writes a dimension:value label (agent_state:<state>) and an event bead
for the audit trail. Labels are indexed and queryable across rigs
("bd list --label agent_state:working").

Update all read paths (GetAgentBead, getAgentBeadInfo) to scan for the
agent_state:* label instead of the dead DB column or description text.
Description text remains as a fallback for legacy beads.

Also fix the second call site in deacon.go (found in competing PR #3283
by EthanJStark — credit for that discovery).

Why bd set-state and not description-only:
- Labels are a generic beads concept (not Gas Town-specific)
- Indexed: bd list --label agent_state:working queries across rigs
- Survives session death; supports crash detection and dashboards
- Description text is unindexed free-form — a fidelity downgrade

The agent_state DB column was removed in beads v0.62.0 when the
agent-as-bead subsystem was extracted as Gas Town infrastructure
(commit 0bd598c, "this belongs in GT, not in beads").

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: thejosephstevens

internal/beads/beads_agent.go

@@ -415,15 +415,22 @@ func (b *Beads) ResetAgentBeadForReuse(id, reason string) error {
 	return nil
 }
 
-// UpdateAgentState updates the agent_state field in an agent bead's description.
+// UpdateAgentState updates the agent_state dimension on an agent bead.
 //
-// bd agent state was removed in beads v0.62.0 as part of observable-states
-// deprecation (ZFC design gt-zecmc). The DB column is no longer maintained
-// by gt; tmux session presence is the authoritative source for liveness.
-// This function updates the description text only, for human-readable bd show output.
+// Uses `bd set-state` (beads 0.62.0+) which writes a dimension:value label
+// (agent_state:<state>) and an event bead for the audit trail. Labels are
+// indexed and queryable ("bd list --label agent_state:working") across rigs.
+//
+// bd agent state was removed in beads v0.62.0 when the agent-as-bead subsystem
+// was extracted as Gas Town infrastructure (commit 0bd598c). bd set-state uses
+// beads' generic dimension:value label convention and is not GT-specific.
+// Approach inspired by PR #3283 (EthanJStark). (gt-4ly)
 func (b *Beads) UpdateAgentState(id string, state string) (retErr error) {
 	defer func() { telemetry.RecordAgentStateChange(context.Background(), id, state, nil, retErr) }()
-	if err := b.UpdateAgentDescriptionFields(id, AgentFieldUpdates{AgentState: &state}); err != nil {
+	// Use runWithRouting so bd can resolve cross-prefix agent beads (e.g., wa-*
+	// agent beads from hq context) via routes.jsonl instead of BEADS_DIR.
+	_, err := b.runWithRouting("set-state", id, "agent_state="+state)
+	if err != nil {
 		return fmt.Errorf("updating agent state: %w", err)
 	}
 	return nil
@@ -609,8 +616,15 @@ func (b *Beads) GetAgentBead(id string) (*Issue, *AgentFields, error) {
 	}
 
 	fields := ParseAgentFields(issue.Description)
-	// Note: agent_state column is no longer maintained (bd agent state removed in
-	// beads v0.62.0, ZFC design gt-zecmc). Description text is authoritative.
+	// Read agent_state from label (authoritative, set via bd set-state).
+	// bd set-state writes "agent_state:<value>" labels — indexed and queryable.
+	// The agent_state DB column was removed in beads v0.62.0 (gt-4ly).
+	for _, label := range issue.Labels {
+		if strings.HasPrefix(label, "agent_state:") {
+			fields.AgentState = strings.TrimPrefix(label, "agent_state:")
+			break
+		}
+	}
 	return issue, fields, nil
 }
 

internal/cmd/deacon.go

@@ -1171,8 +1171,8 @@ func updateAgentBeadState(townRoot, agent, state, _ string) { // reason unused b
 		return
 	}
 
-	// Use bd agent state command
-	cmd := exec.Command("bd", "agent", "state", beadID, state)
+	// Use bd set-state (beads 0.62.0+); bd agent state was removed (gt-4ly).
+	cmd := exec.Command("bd", "set-state", beadID, "agent_state="+state)
 	cmd.Dir = townRoot
 	_ = cmd.Run() // Best effort
 }

internal/daemon/lifecycle.go

@@ -771,7 +771,7 @@ func (d *Daemon) closeMessage(id string) error {
 type AgentBeadInfo struct {
 	ID         string `json:"id"`
 	Type       string `json:"issue_type"`
-	State      string // From DB column (agent_state), fallback to description
+	State      string // From agent_state label (set via bd set-state), fallback to description
 	HookBead   string // From DB column (hook_bead)
 	RoleType   string // Parsed from description: role_type
 	Rig        string // Parsed from description: rig
@@ -840,15 +840,18 @@ func (d *Daemon) getAgentBeadInfo(agentBeadID string) (*AgentBeadInfo, error) {
 		info.Rig = fields.Rig
 	}
 
-	// Use AgentState from description text (authoritative post-v0.62.0).
-	// bd agent state was removed in beads v0.62.0 (ZFC design gt-zecmc), so the
-	// DB column is stuck at "spawning" permanently. Description text is updated
-	// by UpdateAgentState via UpdateAgentDescriptionFields and is the source of
-	// truth. Fall back to DB column only if description is empty (legacy beads).
-	if fields != nil && fields.AgentState != "" {
+	// Read agent_state from label (authoritative, set via bd set-state).
+	// bd set-state writes "agent_state:<value>" labels — indexed and queryable.
+	// The agent_state DB column was removed in beads v0.62.0 (gt-4ly).
+	for _, label := range issue.Labels {
+		if strings.HasPrefix(label, "agent_state:") {
+			info.State = strings.TrimPrefix(label, "agent_state:")
+			break
+		}
+	}
+	// Fall back to description text for legacy beads without label support.
+	if info.State == "" && fields != nil {
 		info.State = fields.AgentState
-	} else {
-		info.State = issue.AgentState
 	}
 
 	// Use HookBead from database column directly (not from description)

internal/daemon/polecat_health_test.go

@@ -28,16 +28,18 @@ func writeFakeTestTmux(t *testing.T, dir string) {
 }
 
 // writeFakeTestBD creates a shell script in dir named "bd" that outputs a
-// polecat agent bead JSON. The descState parameter controls what appears in
-// the description text (parsed by ParseAgentFields), while
-// dbState controls the agent_state database column. updatedAt controls the
-// bead's updated_at timestamp for time-bound testing.
-func writeFakeTestBD(t *testing.T, dir, descState, dbState, hookBead, updatedAt string) string {
+// polecat agent bead JSON. The labelState parameter controls the agent_state
+// label (authoritative source, set via bd set-state). The descState parameter
+// controls the description text fallback. updatedAt controls the bead's
+// updated_at timestamp for time-bound testing. (gt-4ly)
+func writeFakeTestBD(t *testing.T, dir, descState, labelState, hookBead, updatedAt string) string {
 	t.Helper()
 	desc := "agent_state: " + descState
-	// JSON matches the structure that getAgentBeadInfo expects from bd show --json
-	bdJSON := fmt.Sprintf(`[{"id":"gt-myr-polecat-mycat","issue_type":"agent","labels":["gt:agent"],"description":"%s","hook_bead":"%s","agent_state":"%s","updated_at":"%s"}]`,
-		desc, hookBead, dbState, updatedAt)
+	labels := fmt.Sprintf(`["gt:agent","agent_state:%s"]`, labelState)
+	// JSON matches the structure that getAgentBeadInfo expects from bd show --json.
+	// agent_state DB column omitted — removed in beads v0.62.0 (gt-4ly).
+	bdJSON := fmt.Sprintf(`[{"id":"gt-myr-polecat-mycat","issue_type":"agent","labels":%s,"description":"%s","hook_bead":"%s","updated_at":"%s"}]`,
+		labels, desc, hookBead, updatedAt)
 	script := "#!/bin/sh\necho '" + bdJSON + "'\n"
 	path := filepath.Join(dir, "bd")
 	if err := os.WriteFile(path, []byte(script), 0755); err != nil {
@@ -52,8 +54,8 @@ func writeFakeTestBD(t *testing.T, dir, descState, dbState, hookBead, updatedAt
 // beads have independent lifecycles (e.g., agent done/nuked while hook_bead open).
 func writeFakeBDWithHookBead(t *testing.T, dir, agentState, hookBeadID, hookBeadStatus, updatedAt string) string {
 	t.Helper()
-	agentJSON := fmt.Sprintf(`[{"id":"gt-myr-polecat-mycat","issue_type":"agent","labels":["gt:agent"],"description":"agent_state: %s","hook_bead":"%s","agent_state":"%s","updated_at":"%s"}]`,
-		agentState, hookBeadID, agentState, updatedAt)
+	agentJSON := fmt.Sprintf(`[{"id":"gt-myr-polecat-mycat","issue_type":"agent","labels":["gt:agent","agent_state:%s"],"description":"agent_state: %s","hook_bead":"%s","updated_at":"%s"}]`,
+		agentState, agentState, hookBeadID, updatedAt)
 	hookJSON := fmt.Sprintf(`[{"id":"%s","status":"%s"}]`, hookBeadID, hookBeadStatus)
 	script := fmt.Sprintf("#!/bin/sh\n"+
 		"case \"$2\" in\n"+
@@ -169,19 +171,19 @@ func TestCheckPolecatHealth_SpawningGuardExpires(t *testing.T) {
 	}
 }
 
-// TestCheckPolecatHealth_DescriptionOverridesDBColumn verifies that the daemon
-// reads agent_state from the description text (source of truth), not the DB column.
-// bd agent state was removed in beads v0.62.0 (ZFC design gt-zecmc), so the DB
-// column stays at "spawning" permanently. Description text is now authoritative.
-func TestCheckPolecatHealth_DescriptionOverridesDBColumn(t *testing.T) {
+// TestCheckPolecatHealth_LabelStateOverridesDescription verifies that the daemon
+// reads agent_state from the label (source of truth, set via bd set-state), not
+// the description text. A polecat that transitioned from "spawning" to "working"
+// will have a stale description but an up-to-date agent_state label. (gt-4ly)
+func TestCheckPolecatHealth_LabelStateOverridesDescription(t *testing.T) {
 	if runtime.GOOS == "windows" {
 		t.Skip("test uses Unix shell script mocks for tmux and bd")
 	}
 	binDir := t.TempDir()
 	writeFakeTestTmux(t, binDir)
 	recentTime := time.Now().UTC().Format(time.RFC3339)
-	// Description says "working" (truth) but DB column says "spawning" (stale)
-	bdPath := writeFakeTestBD(t, binDir, "working", "spawning", "gt-xyz", recentTime)
+	// Description says "spawning" (stale) but label says "working" (truth)
+	bdPath := writeFakeTestBD(t, binDir, "spawning", "working", "gt-xyz", recentTime)
 
 	t.Setenv("PATH", binDir+":"+os.Getenv("PATH"))
 
@@ -196,13 +198,13 @@ func TestCheckPolecatHealth_DescriptionOverridesDBColumn(t *testing.T) {
 	d.checkPolecatHealth("myr", "mycat")
 
 	got := logBuf.String()
-	// Should NOT skip due to spawning guard — description says "working"
+	// Should NOT skip due to spawning guard — label says "working"
 	if strings.Contains(got, "Skipping restart") {
-		t.Errorf("daemon should use description agent_state (working), not stale DB column (spawning), got: %q", got)
+		t.Errorf("daemon should use label agent_state (working), not stale description (spawning), got: %q", got)
 	}
-	// Should detect crash since description says working + session is dead
+	// Should detect crash since label says working + session is dead
 	if !strings.Contains(got, "CRASH DETECTED") {
-		t.Errorf("expected CRASH DETECTED when description state is 'working' with dead session, got: %q", got)
+		t.Errorf("expected CRASH DETECTED when label state is 'working' with dead session, got: %q", got)
 	}
 }