---
name: beads-state
description: Git-friendly, crash-recoverable state persistence for the Gastown orchestration chipset. Manages agent identities, work items, hooks, convoys, and merge requests as JSON files with atomic write operations.
type: skill
category: state
status: stable
origin: tibsfox
modified: false
first_seen: 2026-03-06
first_path: .claude/skills/beads-state/SKILL.md
superseded_by: null
---
# Beads State Persistence

Filesystem-backed state management for multi-agent orchestration. All state is stored as individual JSON files using atomic write operations. No database dependencies.

## State Entities

### Agent Identity

**Path:** `.chipset/state/agents/{id}.json`

Persistent record of an agent in the topology. Contains role, rig assignment, hook pointer, lifecycle status, and optional ephemeral session ID.

```typescript
interface AgentIdentity {
  id: string;           // Unique identifier (e.g., 'polecat-alpha')
  role: AgentRole;      // mayor | witness | refinery | polecat | crew
  rig: string;          // Parent rig name
  hookId: string;       // Pointer to hook bead in state/hooks/
  status: AgentStatus;  // idle | active | stalled | terminated
  sessionId?: string;   // Present only while agent is active
}
```

### Work Item

**Path:** `.chipset/state/work/{bead-id}.json`

A unit of work flowing through the dispatch pipeline. Created by the mayor, assigned via hooks, tracked through lifecycle.

```typescript
interface WorkItem {
  beadId: string;          // Bead-style ID (prefix-xxxxx)
  title: string;
  description: string;
  status: WorkStatus;      // open | hooked | in_progress | done | merged
  assignee?: string;       // Agent ID (undefined if unassigned)
  hookStatus: HookStatus;  // empty | pending | active | completed
  priority: 'P1' | 'P2' | 'P3';
}
```

### Hook

**Path:** `.chipset/state/hooks/{agent-id}.json`

Current work assignment for an agent. Enforces GUPP (Get Up and Push Protocol) -- one agent, one work item at a time.

```typescript
interface HookState {
  agentId: string;
  status: HookStatus;
  workItem?: WorkItem;     // Present when hook is pending/active
  lastActivity: string;    // ISO 8601 timestamp
}
```

**Constraint:** An agent can hold at most one hook at a time. Setting a new hook on an agent that already has an active hook is rejected. The caller must clear the existing hook first.

### Convoy

**Path:** `.chipset/state/convoys/{id}.json`

Groups related work items for batch tracking. The mayor creates convoys to organize beads and monitor aggregate progress.

```typescript
interface Convoy {
  id: string;
  name: string;
  beadIds: string[];
  progress: number;     // 0.0 to 1.0
  createdAt: string;    // ISO 8601
}
```

### Merge Request

**Path:** `.chipset/state/merge-queue/{id}.json`

Queued for the refinery. Processed strictly sequentially -- no parallel merges. Conflicts block the queue and escalate.

```typescript
interface MergeRequest {
  id: string;
  sourceBranch: string;
  targetBranch: string;
  status: 'pending' | 'merging' | 'merged' | 'conflicted';
  beadId: string;
}
```

## Filesystem Layout

```
.chipset/state/
  agents/          Agent identity JSON files
  hooks/           GUPP hook state per agent
  work/            Work item beads
  convoys/         Batch tracking
  merge-queue/     Refinery merge requests
```

Each entity is a single JSON file. The directory structure acts as the "table" -- listing files is the equivalent of a database scan.

## Durability Contract

### Atomic Writes

All mutations follow a three-step atomic write protocol:

1. **Write** content to a temporary file in the same directory (`.{name}.tmp`)
2. **Fsync** the temporary file to ensure data reaches disk
3. **Rename** the temporary file to the target path (atomic on POSIX filesystems)

This guarantees that a reader always sees either the complete old state or the complete new state, never a partial write. If the process crashes between steps 1-2, only the temp file is left (cleaned up on next startup). If it crashes between steps 2-3, the temp file contains the full new state and can be recovered.

### JSON Format

All JSON output uses `JSON.stringify` with sorted keys. This produces deterministic output that creates clean, minimal diffs when tracked by git. Sorted keys also make manual inspection easier -- fields appear in a predictable order.

```typescript
// Sorted-key serialization
function serialize(data: unknown): string {
  return JSON.stringify(data, Object.keys(data as object).sort(), 2);
}
```

### No Database Dependencies

State is filesystem-only. No SQLite, no LevelDB, no external services. This means:

- State is readable with `cat` and editable with any text editor
- State is trackable by git (JSON diffs show exactly what changed)
- State survives any process crash (atomic writes prevent corruption)
- State works across all platforms (POSIX rename semantics)
- State requires no setup beyond `mkdir -p`

## StateManager API

The StateManager class provides typed CRUD operations for all state entities.

### Construction

```typescript
const manager = new StateManager({ stateDir: '.chipset/state/' });
```

The `stateDir` parameter is configurable. The manager creates subdirectories on first use.

### Agent Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `createAgent` | `(role, rig) => AgentIdentity` | Generate unique ID, write agent JSON |
| `getAgent` | `(id) => AgentIdentity \| null` | Read agent by ID, null if not found |
| `updateAgentStatus` | `(id, status) => void` | Atomic status update |
| `listAgents` | `(filter?) => AgentIdentity[]` | List all agents, optional role/rig filter |

### Work Item Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `createWorkItem` | `(title, description, priority?) => WorkItem` | Generate bead ID, write work JSON |
| `getWorkItem` | `(beadId) => WorkItem \| null` | Read work item by bead ID |
| `updateWorkStatus` | `(beadId, status) => void` | Atomic status update |

### Hook Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `setHook` | `(agentId, beadId) => void` | Assign work to agent (single assignment enforced) |
| `getHook` | `(agentId) => HookState \| null` | Read hook state for agent |
| `clearHook` | `(agentId) => void` | Remove hook assignment |

### Convoy Operations

| Method | Signature | Description |
|--------|-----------|-------------|
| `createConvoy` | `(name, beadIds) => Convoy` | Create batch with member beads |
| `getConvoy` | `(id) => Convoy \| null` | Read convoy by ID |
| `updateConvoyProgress` | `(id) => void` | Recalculate progress from member bead statuses |

## Error Handling

- **File not found:** Returns `null` for get operations. Never throws on missing state.
- **Concurrent writes:** Last writer wins (rename is atomic). For coordination, use the convoy or hook layer.
- **Corrupt JSON:** Log warning, return `null`. Caller decides recovery strategy.
- **Disk full:** Propagates OS error. Temp file cleanup is best-effort.

## Usage Patterns

### Create and Assign Work

```typescript
const agent = await manager.createAgent('polecat', 'my-rig');
const item = await manager.createWorkItem('Fix auth bug', 'JWT expiry not handled', 'P1');
await manager.setHook(agent.id, item.beadId);
```

### Track Convoy Progress

```typescript
const convoy = await manager.createConvoy('Sprint 1', [item1.beadId, item2.beadId]);
// ... after some work completes ...
await manager.updateConvoyProgress(convoy.id);
const updated = await manager.getConvoy(convoy.id);
console.log(`Progress: ${(updated!.progress * 100).toFixed(0)}%`);
```

### Filter Agents by Role

```typescript
const polecats = await manager.listAgents({ role: 'polecat' });
const idle = polecats.filter(a => a.status === 'idle');
```