// Package fs defines the 9P namespace for olliesrv.
//
// The namespace is declared in spec.go using the virtfs EDSL. All session
// and agent state is exposed as files: creating sessions, submitting
// prompts, reading chat history, and observing state changes are all
// file operations.
//
// # Namespace Structure
//
// Root level:
//
//	/agents        - available agent profile names
//	/backends      - available backend names
//	/models        - available models (backend\tmodel per line)
//	/ctl           - server control (invalidate, kill)
//	/generate      - one-shot generation (rdwr)
//	/session/      - session directory
//
// Session level (/session/{name}/):
//
//	env            - session environment variables
//	goal           - session objective (write triggers workflow)
//	agent/         - agents within this session
//	agent/new      - create agent (rdwr)
//
// Agent level (/session/{name}/agent/{agent}/):
//
//	prompt         - submit prompt (write)
//	chat           - conversation history (streaming read)
//	statewait      - block until state changes
//	plan           - agent's plan (survives compaction)
//	ctl            - agent control commands
//
// # Blocking Reads
//
// Files like statewait and eventwait block until their condition is met.
// This is the primary coordination mechanism — clients read these files
// in a loop to react to state changes.
//
// # Implementation
//
// The spec is pure declaration; handlers are closures that capture their
// targets. NewRoot() builds the virtfs.Tree from the spec. The tree is
// served directly by the 9P server.
package fs