## 9P Filesystem: Everything is a File

The 9P namespace is the lowest-level interface to ollie. Everything — sessions,
agents, prompts, tools, state — is a file. The `o` CLI wraps these operations,
but the raw filesystem is the foundation.

### Mounting

```sh
ollie-9p mount unix!/tmp/ns.$USER.$DISPLAY/ollie ~/mnt/ollie
cd ~/mnt/ollie
ls session/
```

Or connect remotely:

```sh
ollie-9p mount tcp!server:9564 ~/mnt/ollie
```

### Raw session operations

```sh
# Create a session
echo "name={sname}" > session/new

# Submit a prompt
echo "fix the bug in main.go" > session/{sname}/agent/{aname}/prompt

# Stream the response
cat session/{sname}/agent/{aname}/chat

# Check state
cat session/{sname}/agent/{aname}/state

# Block until state changes
cat session/{sname}/agent/{aname}/statewait

# Read offset (byte position after user prompt)
cat session/{sname}/agent/{aname}/offset
```

### Network transparency

9P is a network protocol. Mount the agent namespace from any machine and every
session, tool, and config value is accessible as if local:

```sh
# From another machine:
9p -a 'tcp!server:5640' read session/{sname}/agent/{aname}/state
```

No SSH tunneling, no port forwarding, no API gateway.

### Shell composability

Because operations are file I/O, they compose with the full Unix toolkit:

```sh
# Fan out a prompt to all agents
for s in session/*/agent/*/prompt; do echo "run tests" > "$s"; done

# Wait for all agents to finish
for s in session/*/agent/*/statewait; do cat "$s" > /dev/null; done

# Grep all agent plans
grep -r "TODO" session/*/plan

# Monitor costs
cat session/*/agent/*/cost

# Strip block markup from chat output
cat session/{sname}/agent/{aname}/chat | grep -vE '^\[\[\[.*'
```

Pipe agents into `awk`. Filter with `grep`. Schedule with `cron`. Orchestrate
with a 10-line shell script instead of a framework.

### Plan 9 patterns

- **`/net/dns` pattern** — `/complete`, `/generate`, `/route` are stateless
  per-fid: write a request, read back the result
- **`ctl` files** — control operations (stop, kill, rename, compact) are writes
  to a control file, not method calls
- **Blocking reads** — `statewait` blocks until state changes, replacing event
  subscriptions with a simple `cat`
- **Multiplexing** — multiple clients mount the same server simultaneously,
  each with an independent view through per-fid state

### `/generate` — one-shot LLM

```sh
echo 'summarize this repo' | ollie-9p rdwr generate
cat main.go | ollie-9p rdwr generate
echo '{"prompt":"explain recursion"}' | ollie-9p rdwr generate
```

### `/complete` — code completion

Fill-in-the-middle:

```sh
echo '{"file":"main.go","prefix":"func ","suffix":""}' | ollie-9p rdwr complete
```

### `/route` — task routing

```sh
echo 'implement login page' | ollie-9p rdwr route
# backend=anthropic model=claude-sonnet-4-20250514
```

### Key files per agent

| File | Mode | Description |
|---|---|---|
| `prompt` | write | Queue a new turn |
| `fifo` | r/w | Prompt queue (write=enqueue, read=dequeue) |
| `statewait` | read (blocking) | Blocks until state changes |
| `chat` | read (streaming) | Filtered text (no markers/fences) |
| `chat.raw` | read (streaming) | Full markup with block markers |
| `log` | read | Last 64KB of conversation (non-blocking) |
| `plan` | r/w | Scratch space for agent planning |
| `cfg` | r/w | Agent config (key=value) |
| `ctl` | rdwr | Control commands (write cmd, read response) |
| `stats` | read | Token usage, cost, context size (key=value) |
| `name` | r/w | Mutable agent name |
| `id` | read | Immutable agent UUID |
| `proc/{pid}` | read | Detached process output |