storkit: create 329_spike_evaluate_docker_orbstack_for_agent_isolation_and_resource_limiting

TIMMY_BRIEFING.md

@@ -0,0 +1,74 @@
+# Briefing for Timmy — Spike 329
+
+Hey Timmy. You're running inside a Docker container as part of spike 329. Here's everything
+you need to know to pick up where we left off.
+
+## What this spike is
+
+Evaluate running the full storkit stack (server, agents, web UI) inside a single Docker
+container, using OrbStack on macOS for better bind-mount performance. The goal is host
+isolation — not agent-to-agent isolation. Read the full spike doc at:
+
+`.storkit/work/1_backlog/329_spike_evaluate_docker_orbstack_for_agent_isolation_and_resource_limiting.md`
+
+## What's been done (2026-03-21)
+
+### Environment confirmed
+- Debian 12 bookworm, arm64, 10 CPUs
+- Rust 1.90.0, Node v22.22.1, git 2.39.5, Claude Code CLI — all present
+- Running under **OrbStack** (confirmed via bind-mount path `/run/host_mark/Users → /workspace`)
+
+### Key benchmarks run
+Bind-mount directory traversal is **~23x slower per file** than a Docker volume:
+
+| Filesystem | Files | Time |
+|---|---|---|
+| Docker volume (`cargo/registry`) | 21,703 | 38ms |
+| Bind mount `target/` subtree | 270,550 | 10,564ms |
+| Bind mount non-target | 50,048 | 11,314ms |
+
+Sequential I/O is fine (440 MB/s write, 1.3 GB/s read on bind mount). The problem is
+purely stat-heavy operations — exactly what cargo does on incremental builds.
+
+### Two bugs found and fixed
+
+**Bug 1 — `target/` on bind mount** (`docker/docker-compose.yml`)
+Added named Docker volumes to keep build artifacts off the slow bind mount:
+```yaml
+- workspace-target:/workspace/target
+- storkit-target:/app/target
+```
+
+**Bug 2 — missing `build-essential` in runtime stage** (`docker/Dockerfile`)
+The runtime stage copies the Rust toolchain but not `gcc`/`cc`. `cargo build` fails with
+`linker 'cc' not found`. Fixed by adding `build-essential`, `pkg-config`, `libssl-dev`
+to the runtime apt-get block.
+
+### `./..:/app` bind mount
+The original commit had this commented out. Another bot uncommented it — this is correct.
+It lets `rebuild_and_restart` pick up live host changes. The `storkit-target:/app/target`
+volume keeps `/app/target` off the bind mount.
+
+## What still needs doing
+
+1. **Rebuild the image** with the patched Dockerfile and run a full `cargo build --release`
+   benchmark end-to-end. This couldn't be done in the first session because the container
+   was already running the old (pre-fix) image.
+
+2. **Docker Desktop vs OrbStack comparison** — repeat the benchmarks with Docker Desktop
+   to quantify the performance delta. We expect OrbStack to be significantly faster due to
+   VirtioFS vs gRPC-FUSE, but need actual numbers.
+
+## Worktree git note
+
+The worktree git refs are broken inside the container — they reference the host path
+(`/Users/dave/workspace/...`) which doesn't exist in the container. Use
+`git -C /workspace <command>` instead of running git from the worktree dir.
+
+## Files changed so far (uncommitted)
+
+- `docker/Dockerfile` — added `build-essential`, `pkg-config`, `libssl-dev` to runtime stage
+- `docker/docker-compose.yml` — added `workspace-target` and `storkit-target` volumes
+- `.storkit/work/1_backlog/329_spike_...md` — findings written up in full
+
+These changes are **not yet committed**. Commit them before rebuilding the container.