tinytown 0.10.0

A simple, fast multi-agent orchestration system using Redis for message passing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# tt recover

Detect and clean up orphaned agents.

## Synopsis

```bash
tt recover [OPTIONS]
```

## Description

Scans for agents that appear to be running (Working, Starting, Idle, or Draining state) but whose processes have actually crashed or been killed. Marks these orphaned agents as Stopped so they can be pruned or restarted.

An agent is considered orphaned if:
1. It's in Working, Starting, Idle, or Draining state
2. Its log file hasn't been modified in 2+ minutes, OR
3. Its last heartbeat was 2+ minutes ago

## Options

| Option | Short | Description |
|--------|-------|-------------|
| `--town <PATH>` | `-t` | Town directory (default: `.`) |
| `--verbose` | `-v` | Enable verbose logging |

## Examples

### Scan for Orphaned Agents

```bash
tt recover
```

Output when orphans found:
```
🔍 Scanning for orphaned agents...
   🔄 Recovered 'worker-1' (Working) - last heartbeat 5m ago
   🔄 Recovered 'worker-2' (Working) - last heartbeat 3m ago

✨ Recovered 2 orphaned agent(s) (4 total checked)
   Run 'tt prune' to remove them from Redis
```

Output when no orphans:
```
🔍 Scanning for orphaned agents...

✨ No orphaned agents found (3 agents checked)
```

## Common Workflow

After a crash or system restart:

```bash
# 1. Recover orphaned agents (marks them stopped)
tt recover

# 2. Optional: Reclaim tasks from dead agents
tt reclaim --to-backlog

# 3. Clean up stopped agents
tt prune

# 4. Restart needed agents
tt restart worker-1
```

## When to Use

- After system restart or crash
- When agents appear "stuck" in Working, Idle, or Draining state
- Before reclaiming tasks from dead agents

## See Also

- [tt prune](./prune.md) — Remove stopped agents
- [tt reclaim](./reclaim.md) — Recover orphaned tasks
- [tt restart](./restart.md) — Restart stopped agents
- [Error Handling & Recovery](../tutorials/recovery.md) — Recovery tutorial