docs: update for background process changes

- doc/TODO.md: remove stale bgTracker cleanup item, add future considerations
- doc/9p.md: add proc/ section with list, new, new.bg, and per-pid files
- doc/9p.md: document <system-proc-complete> push mechanism
- README.md: update background process description

README.md

@@ -58,7 +58,7 @@ Everything lives under `$XDG_CONFIG_HOME/ollie/` (default: `~/.config/ollie/`)
 | **One-shot LLM** | `o generate "explain monads"` or `echo "prompt" \| o generate` |
 | **Run an agent** | Create a session + agent via 9P — then connect with any frontend ([ellie](doc/ellie.md), KDE (GUI/KRunner/Kate), `o tui`) |
 | **Remote execution** | Set `remote=user@host` in session config |
-| **Background processes** | Pass `"background": true` to any tool — runs with no timeout, output auto-injected, lifecycle tied to session |
+| **Background processes** | Pass `"background": true` to any tool — runs with no timeout, output pushed to agent prompt on completion |
 | **Parallel execution** | Non-conflicting tool calls within a turn run in parallel (scope-based conflict scheduling) |
 | **Agents** | Write a JSON config in `data/agents/` with agent prompt in `data/prompts/` |
 | **Tools** | Drop an executable + `.meta` in `~/.config/ollie/tools/` — load at runtime via `/tool_load` |

doc/9p.md

@@ -111,4 +111,24 @@ echo '{"prompt":"explain recursion"}' | ollie-9p rdwr generate
 | `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 |
+
+### Background processes (`proc/`)
+
+Toolsrv manages background processes. The agent queries toolsrv for the proc list.
+
+| File | Mode | Description |
+|---|---|---|
+| `proc/list` | read | All processes: `pid\tstate\ttool` |
+| `proc/new` | rdwr | Execute tool (blocking) |
+| `proc/new.bg` | rdwr | Execute tool (background, returns pid) |
+| `proc/{pid}/out` | read | Process output buffer |
+| `proc/{pid}/stat` | read | Process status (key=value) |
+| `proc/{pid}/ctl` | write | Control: `term`, `kill`, `signal <N>`, `dismiss` |
+
+When a background process exits, toolsrv pushes the complete output to the agent's prompt as a `<system-proc-complete>` message:
+
+```xml
+<system-proc-complete id="1" cmd="echo test" exit="0">
+output here
+</system-proc-complete>
+```

doc/TODO.md

@@ -1,16 +1,9 @@
+# TODO
 
-## Background Process Tracking Cleanup
+## Future Improvements
 
-The agent maintains a local `bgTracker` (`bgProcs`) that partially duplicates toolsrv's proc state. This creates sync issues:
+### Proc Ownership Filtering
+Currently all agents in a session share the same toolsrv proc namespace. If multi-agent sessions become common, consider adding agent ID filtering to `ListProcs()` so agents only see their own processes.
 
-- `ListProcs()` now queries toolsrv directly (correct)
-- `CollectInterrupts()` still uses local tracker for `LastOutput` diff detection
-- `bgProcs.Add()` is still called when starting background procs
-- `bgProcs.Remove()` is called on dismiss
-
-Consider:
-1. Remove local tracker entirely, track only `LastOutput` map keyed by PID
-2. Or add agent ID to toolsrv Proc struct for proper ownership filtering
-3. Move `LastOutput` tracking to toolsrv (add a "read offset" or "last read hash")
-
-Current state works but is fragile - toolsrv is source of truth for proc list, local tracker is only for interrupt diff detection.
+### Proc GC Tuning
+Background proc GC currently uses a fixed 10-minute TTL after output is read. Consider making this configurable or adding explicit dismiss-on-read semantics for certain use cases.