SeedPass/OVERSTORY_SWARM_TUTORIAL.md

SeedPass Overstory Swarm Runbook (Local Note)

Last verified: March 3, 2026
Repo: /home/user/Documents/GitHub/SeedPass

This is a practical, repo-specific guide for running os-eco agent swarms in SeedPass.

1) Prerequisites

Required CLIs:

• git
• tmux
• bun
• ov
• sd
• ml
• cn
• codex

Quick check:

command -v bun && bun --version
command -v tmux && tmux -V
command -v ov && ov --version
command -v sd && sd --version
command -v ml && ml --version
command -v cn && cn --version
command -v codex && codex --version

Codex auth check:

codex login status || codex login

2) SeedPass-Specific Config That Must Be True

Check .overstory/config.yaml:

• project.canonicalBranch: beta
• quality gates should run Python checks:
  • PATH=".venv/bin:$PATH" pytest -q
  • PATH=".venv/bin:$PATH" bash scripts/run_ci_tests.sh
• runtime.default: codex
• leave top-level models: empty (important for Overstory 0.7.9)

Check .overstory/agent-manifest.json:

• each agent model should be gpt-5.3-codex

Why this matters:

• In this environment, codex exec --model sonnet fails and exits immediately.
• That early exit causes Overstory to throw:
  • Failed to send keys to tmux session "...": can't find pane: ...

3) Prime Context at Start of Session

From repo root:

cd /home/user/Documents/GitHub/SeedPass
ml prime
sd prime
cn prime

4) Pick and Start a Task (Seeds)

sd ready
sd list --status=in_progress
sd list --status=open
sd show <ID>
sd update <ID> --status=in_progress

5) Start tmux Server Before Sling

Overstory needs tmux live before spawning:

tmux has-session -t ov-bootstrap 2>/dev/null || tmux new-session -d -s ov-bootstrap "bash"

If not running, Overstory may fail with:

• Tmux server is not running (cannot reach session ...)

6) Spawn Agents

Status first:

ov status --all --verbose

Spawn lead (hierarchy-compliant):

ov sling <SEEDPASS-ID> --capability lead --name lead-<short>

Spawn builder under lead:

ov sling <SEEDPASS-ID> --capability builder --name b1 --parent lead-<short> --depth 2

Quick debug bypass:

ov sling <SEEDPASS-ID> --capability builder --name b1 --runtime codex --force-hierarchy

Watch activity:

ov status --all --verbose
tmux ls | grep overstory
tmux capture-pane -pt overstory-SeedPass-b1:0.0 | tail -n 60

Attach manually:

tmux attach -t overstory-SeedPass-b1

Detach: Ctrl-b d

6.1) Monitor Agents (Second Terminal)

Open a second terminal in the repo and run one of these:

Snapshot status:

ov status --all --verbose

Live event stream:

ov feed --follow --interval 1000

Live dashboard UI:

ov dashboard --all

Inspect one agent continuously:

ov inspect <agent-name> --follow --interval 2000

Watch tmux sessions directly:

tmux ls | grep overstory
tmux capture-pane -pt overstory-SeedPass-<agent-name>:0.0 | tail -n 80

7) Common Failures and Fixes

A) can't find pane during sling

Most likely in this repo: invalid model mapping.

Fix:

1. Set every agent model in .overstory/agent-manifest.json to gpt-5.3-codex.
2. Keep .overstory/config.yaml top-level models: empty.
3. Clean stale state and retry:

ov clean --worktrees --branches --sessions --all
ov sling <SEEDPASS-ID> --capability builder --name b1 --runtime codex --force-hierarchy

B) Tmux server is not running

Fix:

tmux new-session -d -s ov-bootstrap "bash"

Then rerun sling.

C) branch ... already exists or agent stuck as booting

Fix:

ov clean --worktrees --branches --sessions --all

Then retry with a fresh agent name if needed.

D) Coordinator cannot spawn "builder" directly

Hierarchy is enforced. Either:

• spawn lead first and then spawn builder under lead, or
• use --force-hierarchy for quick debugging.

8) Merge and Close Workflow

After agent work is complete:

ov status --all --verbose

Run local quality gates on canonical branch before finalizing:

PATH=".venv/bin:$PATH" pytest -q
PATH=".venv/bin:$PATH" bash scripts/run_ci_tests.sh

Close task and sync trackers:

sd close <ID>
sd sync
ml learn
ml record <domain> --type <type> --description "..."
ml sync
cn sync
git push

9) Useful Recovery Commands

Stop one agent:

ov stop <agent-name>

Nuclear cleanup:

ov clean --worktrees --branches --sessions --all

Recommended default after every swarm run:

# stop any named agents from the run (if still active)
ov stop <agent-name> || true

# then fully reset overstory runtime state
ov clean --worktrees --branches --sessions --all

# verify empty
ov status --all --verbose

10) Known-Good Smoke Test

The following command path worked on March 3, 2026 in this repo:

tmux new-session -d -s ov-bootstrap "bash"
ov clean --worktrees --branches --sessions --all
ov sling SeedPass-95c5 --capability builder --name b1 --runtime codex --force-hierarchy
ov status --all --verbose

11) Running 10+ Agents Reliably

What worked in this repo:

• 10 tmux-backed Codex agent sessions launched in one run.
• Worktree agents successfully sent ov mail messages to coordinator.

Important caveats:

• Launching many ov sling commands at once can trigger SQLite contention (database is locked).
• Multiple builders on the exact same Seeds ID can be blocked by task-claim protection.

Recommended pattern:

# 1) clean start
ov clean --worktrees --branches --sessions --all
tmux has-session -t ov-bootstrap 2>/dev/null || tmux new-session -d -s ov-bootstrap "bash"

# 2) use one task per worker when possible
#    (or intentionally bypass checks only for controlled smoke tests)

# 3) stagger launches slightly (reduces lock contention)
for i in $(seq 1 10); do
  ov sling <TASK-ID-$i> --capability builder --name b$i --runtime codex --force-hierarchy
  sleep 0.4
done

# 4) monitor
ov status --all --verbose
ov feed --follow --interval 1000

If one launch fails with database is locked:

sleep 1
ov sling <TASK-ID> --capability builder --name <retry-name> --runtime codex --force-hierarchy