ollie/doc/boot-sequence.md

Boot Sequence

How olliesrv starts up, from main() to serving 9P requests.

Call chain

main()
  │
  ├── env.EnsureDefaults()          — populate $XDG_CONFIG_HOME/ollie/ if missing
  ├── olog.NewSink()                — stderr/stdout log sink
  ├── fs.NewModelCache()            — async LLM model list (prefetched later)
  │
  ├── fs.NewRoot(cfg)               ← composition root
  │     │
  │     ├── session.Init(...)       — set package-level config (ctx, dirs, logger)
  │     ├── build RootState         — allocate SessionNodes map
  │     ├── fsedsl.BuildTree(spec)  — walk fs/spec.go, produce *Tree with lazy resolution
  │     └── session.RestoreAllSessions()
  │           └── for each .json in sessions/active/
  │                 ├── unmarshal PersistedSession
  │                 ├── rebuild Session + Agents (paused)
  │                 └── register in session registry
  │
  ├── bypass.NewBroker(...)         — start bypass socket (sandbox escape approval)
  ├── New(serverCfg)                — create 9P server wrapping the tree
  ├── net.Listen("unix", sockPath)  — bind the 9P socket
  └── accept loop                   — each conn gets srv.Start(conn)

Why fs.NewRoot is the composition root

The 9P filesystem IS the runtime. Every session, agent, and tool server is reachable only through the namespace. So the filesystem package owns initialization: it creates the tree, initializes the session registry, and restores persisted state — all before a single 9P connection is accepted.

main.go is deliberately thin: parse flags, set up logging, call fs.NewRoot, start the listener. All domain logic lives in the packages.

Key ordering constraints

1. session.Init() must be called before RestoreAllSessions() (sets pkg config).
2. RootState must be allocated before BuildTree() (closures capture the pointer).
3. BuildTree() must complete before RestoreAllSessions() (restored sessions create nodes in the tree).
4. The bypass broker starts AFTER the tree is built but BEFORE the accept loop (tool execution needs the broker socket).

Session restoration

Restored sessions come back paused. They have agents with history but no running tool server or LLM connection. The first Resume (via ctl write) re-dials the tool server and reconnects the backend.