feat(hierarchy): unify Agent + Session — single source of truth

[aterrylu]

Problem

After server restart (`make prod` / `make deploy`), the dashboard's hierarchy view sometimes drops agents that the flat view still shows — and the inverse pattern: new agents spawned post-restart appear in hierarchy view, while pre-restart agents do not. PR #152 fixed several adjacent symptoms but the underlying class of bug remained: `/api/sessions` and `/api/org` are independent projections of the same `sessions.json` file, computed through different filters that are allowed to drift.

Solution: one canonical `Agent` entity, one endpoint, one source of truth

The hierarchy view and flat view now read from the same data. Disagreement becomes structurally impossible — not patched, but ruled out by the data model itself.

```mermaid
graph LR
subgraph Before[Before — two sources]
direction TB
A1[/api/sessions] --> Filter1[filter exited?] --> Flat1[Flat view]
B1[/api/org] --> Filter2[filter exited
+ chooseCanonical
+ name resolution] --> Hier1[Hierarchy view]
style Filter1 fill:#fcc
style Filter2 fill:#fcc
end

subgraph After[After — one source, derived views]
direction TB
C1[/api/agents] --> Store["useStore.agents"]
Store --> Flat2[Flat view]
Store --> Hier2[Hierarchy view]
style Store fill:#cfc
end
```

Architecture

Data model

• `Agent` is the canonical durable entity (lives in `@autonomos/core`)
• `agent.id` is a stable UUID, never changes; for migrated agents it equals the old `claudeSessionId` to preserve continuity
• `agent.managerId: UUID | null` — ID-keyed manager refs, rename-proof, no name-collision logic
• `agent.status: "running" | "exited"` + `exitReason` — minimal surface; archived/detached deferred until they have real UX
• `agent.providerSessionId` — provider-specific (CC sessionId, Codex, Gemini); decouples agent identity from provider implementation

Persistence

One JSON file per agent at `~/.autonomos/agents/.json`:

• Atomic per-file writes (`.tmp` + rename)
• Inspectable over plain SSH (no DB binary needed)
• Rsync-friendly for the planned desktop+SSH pivot
• Future high-churn data (audit log, telemetry) can graduate to SQLite when it earns it

API contract

Method	Path	Effect
`GET`	`/api/agents`	All agents (flat list — client derives hierarchy)
`GET`	`/api/agents/tree`	Server-built nested view for clients that can't compose trees
`GET`	`/api/agents/:id`	Single agent (id-or-name)
`POST`	`/api/agents`	Spawn (accepts `manager` name or `managerId`)
`PATCH`	`/api/agents/:id`	Rename / template / project (`If-Match` for optimistic concurrency)
`POST`	`/api/agents/:id/manager`	Set/clear manager — cycle-checked
`POST`	`/api/agents/:id/attach`	Resume an exited agent (re-spawn PTY)
`POST`	`/api/agents/:id/kill`	Kill PTY, keep record (status: exited)
`DELETE`	`/api/agents/:id`	Hard delete; `?reassignTo=<uuid
`WS`	`/ws/agents`	Typed delta stream + `reconcile` snapshot on (re)connect

Deleted: `/api/sessions`, `/api/sessions/:id`, `/api/org`, `/api/org/manager`. No backwards-compat shim.

WebSocket events

Six past-tense single-word events plus `reconcile`:

```ts
type AgentDelta =
| { type: "agent.created"; agent: Agent }
| { type: "agent.updated"; id; patch; version }
| { type: "agent.reparented"; id; managerId; version }
| { type: "agent.attached"; id; provider; providerSessionId; version }
| { type: "agent.exited"; id; exitReason; version }
| { type: "agent.deleted"; id }
| { type: "reconcile"; agents: Agent[] };
```

Every event has a real emitter today. Future event types (e.g. `agent.detached`, `agent.archived`) will be additive when the corresponding state/feature lands.

Migration

Server-startup, idempotent, process-manager-agnostic:

```

1. ensureAgentsDir() / migrateIfNeeded()
   • if ~/.autonomos/agents/ exists → already migrated, no-op
   • elif ~/.autonomos/sessions.json → migrate, rename source to .premigration-
   • else → fresh install
2. resumeActiveAgents()
3. serve() begins listening
   ```

Runs identically under pm2, npx, bun, manual node, or the planned desktop-bootstrapped SSH server. The migration is purely a function of the program starting, not of who started it — critical for the upcoming desktop+SSH architecture pivot.

Backup file (`sessions.json.premigration-`) is kept indefinitely for manual rollback.

Dashboard

• `fetchSessions()` → `/api/agents`, mapped to legacy `SessionInfo` shape at the boundary
• HierarchyPanel + Sidebar both fetch `/api/agents/tree` (single source for the tree shape)
• `mergeOrgWithSessions` retained as the merge function but now operates on consistent data
• localStorage UI prefs (`hierarchyOrder`, `showExitedAgents`, `sidebarViewMode`) untouched — they belong to the desktop, not the remote, exactly per the VS Code Remote precedent

Test plan

• `make check` clean: 283 tests pass, biome lint clean, full TypeScript build clean
• Migration logic exercised by passing tests
• Manual QA against `make dev` (NOT prod): spawn 3 agents with hierarchy → restart → verify both views show identical sets
• Manual QA: rename an agent via /rename → verify hierarchy unchanged (key demonstration of rename-proofness)
• Manual QA: `set_manager` cycle attempt → verify 409 rejection
• Manual QA: hard-delete parent without flags → verify 409 with dependent list

Risk

• Migration is one-way per host but produces a backup. Rollback is documented (5 commands: stop, rm agents/, rename .premigration-* back, redeploy old).
• Channel-server endpoints renamed; existing channel servers will need to restart to pick up the new code (normal flow).
• WebSocket `/ws/agents` is new infrastructure; if subscribers fail, dashboard falls back to 5s poll of `/api/agents/tree` (the existing pattern).

What's NOT in this PR (deferred)

• Audit log SQLite layer — not needed until restart banner / time-travel debugging is real
• Drag-to-reparent UI (`set_manager` is API-only)
• `agent.archived` / `agent.detached` states (additive when the corresponding UX lands)
• Restart banner ("N agents resumed; M crashed")
• Server packaging as `npx @autonomos/server` (separate PM2→npx migration)

🤖 Generated with Claude Code

[nox-0x]

This is a thorough, well-designed refactor. The unified Agent entity, per-file persistence, typed WebSocket deltas, and optimistic concurrency all look correct. No critical issues found. The migration path is safe (atomic writes, rollback on failure, idempotent on re-run). Dashboard adapter layer correctly translates between old SessionInfo shape and new Agent shape. Left one minor suggestion about the manager name lookup edge case — non-blocking. LGTM.