One host, many agents, one journal.

Still carrying too much

The one-line thesis

Removing the browser PTY path eliminated the strongest argument for a big-bang backend migration. The remaining problem is not the runtime — it is that six files hold most of the system’s decisions.

lfg serve

The control API plus background pumps: journal, send queue, APNs watcher. One Bun process, one event loop.

LFG for iOS / iPadOS

Monitoring and control. Offline-durable GRDB cache, cursored SSE, durable outbox, push and Live Activity.

LFG desktop for macOS

Lightweight cross-host launcher into iTerm2. No local database, no stream, no push, no editing.

CLI integrations

Markdown-defined insight agents and a WhatsApp sidecar. Both candidates for a Phase 0 product decision.

iOS / iPadOS app target

• App & lifecycle — LFGApp · RootView · SettingsView. Scene entry, host setup, adaptive navigation, foreground/background and deep-link lifecycle.
• Application state — SessionStore (2,615) · HostLink · BackgroundSender. Multi-host orchestration, REST snapshots plus journal reduction, commands, optimistic state and outbox, stream health, background-safe sends.
• Screens — SessionListView (1,054) · SessionDetailView · NewSessionView · NewSession/*. Group, filter, search; transcript and control surface; create, resume and fork flows.
• Presentation — Components · MessageComposer · RichContent · Theme · UnreadBadges. Reusable UI, attachments, Markdown/tool/media rendering, read affordances.
• Notifications — PushManager · LiveActivityManager · FleetActivityController · RetiredSessionActivity. APNs lifecycle and navigation, push-to-start tokens, fleet activity projection.

LFGCore — the shared, simulator-free core

• Contract & transport — Models · LFGClient · SSEParser · HostEvents. Codable contract, REST/SSE client, lenient decoding.
• Identity & health — MultiHost · HostConfig · HostState · HostHealth. Multi-host identity and one host-health state machine.
• Persistence — LFGStore · LFGStoreRecords. GRDB store and records; the durable local authority.
• Reducers — OptimisticSendReconciliation · ReadState · RecentDirs. Transcript and display reduction, optimistic-send reconciliation, read/unread.
• Activity — Push · FleetActivitySnapshot · LFGFleetAttributes. Push and ActivityKit data shared with the widget target.

LFGCore/Tests covers these seams without a simulator. ios/project.yml is the XcodeGen source of truth; ios/LFGWidgets supplies the ActivityKit widget.

Host, events and environment

Sessions and lifecycle

Control and queue

Push

21 static path literals plus 16 session-scoped UUID-matched routes, all matched by hand-rolled string and regex comparison inside a single fetch handler.

iOS / iPadOS requirements

• iOS / iPadOS 17.2+, Swift 6 strict concurrency
• GRDB for the durable local store, MarkdownUI for GFM rendering
• Network reachability to every configured host, typically over Tailscale
• Optional APNs credentials on those hosts for push and Live Activity
• XcodeGen (ios/project.yml) is the project source of truth

Host and macOS requirements

• Bun ≥ 1.3.14, single long-lived serve process
• tmux for CLI runtimes; Claude Code and/or Codex CLI installed
• Linux for full process enumeration — /proc is used for cwd resolution
• macOS launcher targets macOS 26, needs iTerm2 automation permission
• Tailscale or an equivalently private network — mandatory, not optional

Core invariants

• One global producer writes live deltas. Clients never cause the server to create per-session transcript-tail pumps.
• Journal sequence is monotonic within a database lifetime. A cursor gap triggers resync rather than guessing.
• A client-id send is idempotent, and a durable send is never owned by a SwiftUI view lifecycle.
• Normalized transcript identity is the client-facing key — not the tmux name, which is only used for process ownership and owner tags.
• Foreign fresh leases are respected before resume or control. Close releases the local lease but never deletes transcript history.
• UI status is a projection of hook, transcript, pane and process facts.
• Clients decode leniently, servers validate strictly — native clients tolerate missing or older fields; server inputs are validated at each command boundary.
• Nothing assumes the API is safe on a public network.

Architecture hazards

• Single-process Bun server. One event loop serves all HTTP and both pumps. Synchronous subprocess fan-out on a hot path stalls everything.
• No bare setInterval fan-out over a session collection — a growing collection turns the tick into a spawn storm. Batch or stagger.
• No /proc on macOS. listSessions enriches via /proc/<pid>/cwd. On macOS, CLI and tmux sessions will not enumerate — expected, not a bug.
• Bun auto-loads .env. ps eww does not show a Bun process’s effective environment.
• Restart by port, not by pattern. Kill via lsof -ti :8766; stale processes silently keep the port. Then probe a changed endpoint before calling the deploy done.

The tmux send path — two traps

• Newlines are Enter. send-keys -l transmits byte-for-byte, so an embedded \n submits early and fragments a multi-line message. Insert via bracketed paste (load-buffer + paste-buffer -p) so Claude collapses it to a single pasted chip and submits it whole.
• Do not gate Enter on re-finding your text. A busy Claude swallows input into its own queue and clears the composer, so a composer scrape misfires. Confirm via transcript growth when idle, or composer-cleared → queued when busy.
• codex inside a claude pane breaks that session’s send path. Two session rows claim one pane; the collision guard nulls tmuxTarget and sends 409. Fingerprint: tmuxName set but tmuxTarget: null.

Failure behavior the clients guarantee

• Offline — durable cached state stays renderable; the list and transcripts still work with no host reachable.
• Stream loss — reconnect with the persisted per-host cursor; a watchdog catches a silent stream that never errors.
• Unserviceable cursor — the server emits event: resync with its head; the client full-refreshes over REST and resets.
• Send failure — surfaced as a failed queue row with retry, delete and send-now, never silently dropped.
• Host unreachable — reported explicitly rather than presented as an empty session list.
• Lease conflict — resume and fork return a conflict instead of two hosts driving one transcript.

Backend — from one fetch handler to typed controllers

Session domain — from one file to five seams

Make the backend/Swift contract executable

TypeScript handlers and lenient Swift Codable models currently evolve independently; route strings are duplicated and only selected builders and decoders have tests.

• Define compact JSON Schema / OpenAPI for external request, response and event envelopes.
• Generate only DTOs and route constants if generation is stable; otherwise validate bodies with Zod and run fixture contract tests against the real Swift decoders.
• Keep lenient response decoding for rolling upgrades; make required command inputs strict.
• Adopt a compatibility rule: servers may add fields; removals and renames require a migration window.

Extract HTTP controllers

• First extract pure validators and controller functions, snapshot-testing status, body and headers for every current route.
• Inject Journal, queue, session catalog, runtime and push dependencies rather than reaching for module singletons.
• Avoid adopting a framework unless the small router itself becomes a burden — the win is separation and testability, not routing features.

Split the store behind one facade

• Keep SessionStore as the only environment-facing @Observable surface.
• Move mechanics into HostCoordinator, SessionRepository, Outbox, SessionProjection, SessionCommands.
• Views read published query projections and invoke commands only.
• Characterize cold launch, offline list, optimistic send and create, id remap, resync, deep link and transfer before moving each seam.

Capabilities, persistence and the hot path

• Replace agent-kind branching with the RuntimeDriver capability interface.
• Add a tiny atomic JSON record helper — schema validation, temp-file plus rename, version and corruption reporting — for managed, titles, users, host identity, registry and push tokens. Keep high-churn queue and journal state in SQLite.
• Do not migrate every small file into one database. Inspectability is genuinely valuable for a self-hosted tool.
• Cache one discovery snapshot per pump tick, use async subprocesses for request work, cap collector and runtime concurrency.

Fill the verification gaps

• Start the Bun app with fake dependencies and contract-test every route — including method mismatch, malformed JSON, ranges, stale cursors and conflicts.
• Add one end-to-end test for create → send → queue event → transcript reconciliation against a fake runtime.
• Add macOS model and API tests independent of iTerm automation.
• Add shell syntax and release-bundle assertions to CI so deprecated artifacts cannot re-enter packaging.
• Track p50/p95 session enumeration, event-pump duration, cursor resync count and send confirmation latency in structured logs.

Adopt an active-document policy

The repository holds far more historical .claude, .codex, delegation, verification and improvement-log material than current product documentation.

• Keep one current system map, current feature docs and decision records.
• Archive or remove superseded plans and evidence on a cadence.
• Mark historical documents with status and replacement links so search results stop masquerading as the current API.

Total working-tree diff: 396 insertions, 5,901 deletions across 76 files.

The runtime-variant budget is contingent on the Phase 0 usage inventory, not assumed.