Hangar

01What Hangar is

Hangar gives ainb a managed-agent control plane: a place to file work as issues, assign them to agents (Claude / Codex / Gemini), watch tasks march through a lifecycle on a kanban board, schedule recurring work with autopilots, curate reusable skills & agent templates, and observe the whole fleet's health — all from the terminal.

It is deliberately loosely coupled. A standalone ainb-hangar-daemon owns the data plane (SQLite, the task FSM, the cron scheduler, the agent runner). The TUI is a plugin (hangar-tui) that the host ainb binary loads and that talks to the daemon over a unix-socket JSON-RPC contract. The plugin holds zero domain logic — it subscribes, pulls snapshots, renders, and forwards key intents. This means the control plane runs (autopilots fire, tasks dispatch) whether or not a TUI is attached.

02System architecture

Five Rust components in three planes: the host + plugin (presentation), the daemon (control), and the store + SQLite (data). Two cross-cutting crates — ainb-hangar-core (IO-free domain types) and ainb-hangar-proto (wire types) — are shared by everything.

The components

The transport

The plugin dials ~/.ainb/hangar/hangar.sock via the host unix_socket_dial capability and speaks the same JSON-RPC framing the host uses over stdio. The daemon resolves a workspace identifier (slug or id) to the real row before scoping any query — the guard that closed the cross-tenant IDOR. Plugin subprocesses are spawned with kill_on_drop(true) plus an OS leak-guard (PR_SET_PDEATHSIG on Linux, setpgid + kill(-pgid) on macOS).

03Dependency graph

Internal crate dependencies

core is the root and depends on nothing internal (so it stays IO-free + trivially testable). store and proto both build on core; the daemon ties all three together. The plugin depends only on proto + the SDK — never on the daemon or store crates — so it cannot smuggle in domain logic.

Key external dependencies

04Data & control flow

Two loops run continuously and independently: the dispatch loop (control plane — turns issues into running agent tasks) and the render loop (data plane — turns daemon state into TUI pixels).

Dispatch loop (control)

1. ainb hangar issue create --assign <agent> (or an autopilot tick) enqueues an agent_task_queue row.
2. The daemon claim loop atomically claims the oldest queued task for an idle runtime (queued → dispatched), respecting per-agent max_concurrent_tasks.
3. It materialises skills into the task's per-task directory at the provider-native path (.claude/skills/, .codex/skills/, .agent_context/skills/ …) — copied, scripts chmod 0755, kept outside the worktree git root so git status stays clean.
4. It spawns the provider in an isolated git worktree (dispatched → running), streaming the transcript.
5. On a terminal transition the FSM finalize path runs idempotently: it stamps done/failed/cancelled, cascades autopilot_run.completed_at when the task belongs to an autopilot run, and captures any gh pr create URL into result.pr_url.

Render loop (data)

1. The plugin sends workspace/subscribe for the active workspace.
2. On the ack it fires snapshot RPCs — hangar/issues_list, tasks_list, agents_list, skills_list, autopilots_list, daemon_health — which the daemon answers from the store (resolving slug→id, scoping by workspace).
3. The plugin folds the wire rows into screen state and renders.
4. Async events (TaskStarted/TaskFinished, autopilot.tick_skipped, skill updates) stream back over the subscription for instant feedback; the next snapshot reconciles authoritatively, so a dropped event self-heals.

05Task lifecycle (FSM)

Every unit of agent work is an agent_task_queue row walking a strict finite-state machine. The transition table is exhaustively defined in ainb-hangar-core and enforced by the store's finalize services.

• Idempotent finalize — concurrent complete-vs-cancel resolves deterministically (first wins, loser no-ops); a terminal row never re-transitions.
• Retry — a failure with a retryable reason (e.g. runtime offline) spawns a child task linked by parent_task_id, capped by max_attempts; agent_error does not retry.
• TTL sweepers — stale queued (2h) / dispatched (5min) / running (2.5h) rows are swept to failed in idempotent batches (cap 500).
• Autopilot cascade — finalising a task carrying an autopilot_run_id stamps the run's completed_at in the same path.

06Data model

A single SQLite database, workspace-tenant from migration 0001. Every row is scoped to a workspace; every by-id query carries the workspace guard (the IDOR fix). The schema is kept Postgres-compatible for a future server backend.

07Plugin host capabilities & security

The plugin runs as a separate process and can only reach the host through declared, gated capabilities in its manifest.toml. Each capability is a Bool or an allow-List; the runtime enforces the grant before any privileged action.

08Autopilots & the cron scheduler

An autopilot is a cron expression + an agent + instructions. A single daemon task drives all of them.

• The loop sleeps until the earliest next_tick_at across enabled autopilots, via a tokio::select! over sleep, shutdown, and a wake signal (used by tests' clock-advance).
• At fire time it re-checks concurrency: if count(autopilot_run WHERE completed_at IS NULL) ≥ max_concurrent_runs it skips and emits autopilot.tick_skipped; otherwise fire_autopilot_tick inserts the run + enqueues the task in one transaction.
• It recomputes the next tick anchored on now (not the stale tick) to avoid replay storms; no enabled autopilots → 60s re-poll.

09Feature catalogue — what a user does

Every Hangar feature is reachable two ways: a TUI screen (open Hangar with g, then a hotkey) and/or the ainb hangar <noun> CLI.

TUI screens & hotkeys

CLI

10Feature × test coverage

Built test-first: every feature carries an acceptance test (unit/integration), and most carry an e2e tripwire — a real test that drives ainb tui in a tmux pane (or the daemon over its real socket) and asserts the rendered/persisted result, per the tmux-ui-tripwire discipline.

Coverage summary

11How it was built — phases P0–P9

Per-bead TDD (RED → GREEN → review → scoped gate → close), each phase capped by e2e tripwires.

P0–P8 complete and verified; P9 (gh integration ✅, PR badge ✅, CI matrix ✅) in the release-prep stretch — draft PR feat/multica → main (#179) open, target tag v2.0.0.