|
2 | 2 |
|
3 | 3 | Project: **etude** — an install kit and docs for running a Claude Code-like coding agent on open-weight models. Three tiers: local, LAN peer, Ollama Cloud. |
4 | 4 |
|
5 | | -**Status**: Harness verified end-to-end on the M3 Air (install + Level 5 smoke + agentic tool calling). Repo **public** on GitHub. `status.sh` audit tool shipped. **`etude` front-door command shipped (Session #06)** — health + drift check + glass-box opencode/ollama/etude updates, then hands off to opencode; its live TUI handoff is not yet interactively verified. opencode upgraded 1.4.7 → 1.15.13. Mac-air-24gb is the only fully-verified tier. Next up — close out `etude` end-to-end (verify the live TUI handoff interactively, add a `test.sh` Level 5 timeout, investigate the opencode 1.15 headless-`run` hang), then the RTX 5080 PC / Windows install (gpu-16gb). Other tiers use the same variant pattern but remain untested. |
| 5 | +**Status**: Harness verified end-to-end on the M3 Air (install + Level 5 smoke + agentic tool calling). Repo **public** on GitHub. `status.sh` audit tool shipped. **`etude` front-door command shipped (Session #06)**; its live TUI handoff is not yet interactively verified. **Session #07 (2026-10-13) refreshed the public kit**: dead tags fixed, a watchlist of newer models added (Qwen 3.5/3.6, Devstral Small 2), install guides rewritten to match the harness, `test.sh` Level 5 timeout added, opencode-major guard in `etude`. Versions current at refresh: Ollama 0.40.3, opencode 1.19.0. The author's Mac currently has **no local models pulled** (disk space), so nothing was re-run end to end on 0.40. Mac-air-24gb is the only fully-verified tier (April 2026). Next up: verify the live TUI handoff, then promote watchlist models by testing them on real hardware. |
6 | 6 |
|
7 | 7 | --- |
8 | 8 |
|
@@ -75,32 +75,35 @@ Added in session #04: |
75 | 75 |
|
76 | 76 | Still unverified: |
77 | 77 | - **`etude` live TUI handoff (Session #06).** `etude`'s health checks + `--dry-run` are verified on the M3 Air; the actual `exec opencode` into the interactive TUI has NOT been watched. Run `etude` interactively and confirm it drops into a working session. |
78 | | -- **opencode 1.15.13 headless `opencode run` (Session #06).** Intermittent: passed twice in agent `test.sh` runs, hung 12.5h once. `test.sh` Level 5 has no timeout (macOS lacks `timeout`), so a hang blocks indefinitely. Investigate root cause (config-schema migration from 1.4? stdin/TTY wait? model-load contention?) and add a portable timeout to Level 5. |
| 78 | +- **~~opencode headless `opencode run` hang~~ — explained in Session #07.** It's upstream: anomalyco/opencode#38723 reports `opencode run` intermittently hanging before it creates a session (44% success over a day, reproduced on 1.17 and 1.18, no fix as of 2026-10-13). `test.sh` Level 5 now runs it in the background with a portable deadline (default 300s, `ETUDE_L5_TIMEOUT`), stdin closed, and a plain-language failure. Verified against stub `opencode` programs (hang, success, nonzero exit, wrong answer); not yet run against a real model on Ollama 0.40. |
| 79 | +- **Session #07 refresh, unexercised parts.** Everything below was checked by dry run, tag lookup on ollama.com, or stub tests only: the install path on Ollama 0.40.3 / opencode 1.19.0; the rewritten `docs/install-macos.md` (describes the harness, so lower risk); the rewritten `docs/install-windows.md` (PowerShell Modelfile variant recipe and config path are unverified); the `glm-5.3:cloud` / `kimi-k3:cloud` template entries (tags exist; cloud path never tested). |
79 | 80 | - **Fresh `brew install --cask ollama` branch of Phase 4.** Session #03 couldn't exercise it — Ollama.app was already on the M3 Air (downloaded directly, not via cask). First machine without Ollama.app is the target. *(De-prioritized — the M1 Air session was dropped; see Parking lot.)* |
80 | 81 | - **Daemon auto-start after a fresh cask install.** Currently `open -a Ollama` with `sleep 2` retry, untested against a cold machine. |
81 | | -- **All tiers other than mac-air-24gb.** `mac-light`, `mac-pro-32gb`, `mac-heavy-64gb`, `mac-max`, and every `gpu-*` tier are registry entries + config templates + (now) variant recipes without a real run. The variant pattern is model-agnostic, so the risk is memory/fit (e.g. `qwen3-coder-next:80b-128k` on mac-max), not tool-calling reliability. |
| 82 | +- **All tiers other than mac-air-24gb.** `mac-light`, `mac-pro-32gb`, `mac-heavy-64gb`, `mac-max`, and every `gpu-*` tier are registry entries + config templates + (now) variant recipes without a real run. The variant pattern is model-agnostic, so the risk is memory/fit (e.g. `qwen3-coder-next:q4_K_M-128k` on mac-max), not tool-calling reliability. |
82 | 83 | - **`install-windows.md`** — entire Windows path, entirely unverified. |
83 | 84 | - **LAN-serve flow** (Air → desktop Ollama, or vice versa). LAN templates now reference variant tags too; the peer machine would need to have run `install.sh` (or manually `ollama create` the variant) for cross-machine calls to resolve. |
84 | 85 | - **Ollama Cloud auth / `:cloud` model pull** — see open threads. |
85 | | -- **`install-macos.md` prose** — deferred from session #03, needs a full rewrite to match the harness (currently documents the old brew-formula path and has no mention of the variant tag pattern). |
| 86 | +- **`install-macos.md` prose** — rewritten in #07 to match the harness. The manual path in it hasn't been walked on a fresh Mac. |
86 | 87 |
|
87 | 88 | --- |
88 | 89 |
|
89 | 90 | ## Work queue |
90 | 91 |
|
91 | 92 | ### P1 (active) |
92 | 93 |
|
93 | | -**Close out `etude` end-to-end (Session #06 follow-ups).** We shipped the front door with an unverified launch path and a real hang finding — verify what we shipped before building more. Doable on the M3 Air. Three parts: (a) run `etude` interactively and confirm the `exec opencode` handoff drops into a working TUI session; (b) add a portable timeout to `test.sh` Level 5 so a hung `opencode run` fails fast instead of blocking (macOS has no `timeout` — use a bash background+sleep+kill pattern); (c) investigate the opencode 1.15 headless-`run` intermittent hang (config-schema migration from 1.4? stdin/TTY wait? model-load contention?). |
| 94 | +**Verify the `etude` live TUI handoff.** Run `etude` interactively and confirm the `exec opencode` handoff drops into a working session. Needs a model pulled (`qwen3:8b` is 5.2GB). *Parts (b) Level 5 timeout and (c) the hang investigation were closed in Session #07: the hang is upstream (anomalyco/opencode#38723).* |
| 95 | + |
| 96 | +**Promote watchlist models.** `tiers.tsv` now carries `watching` rows for `qwen3.5:4b`, `qwen3.5:9b`, `qwen3.6:27b-coding`, `qwen3.6:35b-a3b-coding`, `devstral-small-2:24b`. Each needs the README→SUMMARY tool-calling test through opencode on real hardware before flipping to `good` and taking over a daily slot. `qwen3.5:9b` is the obvious first candidate (Ollama's own opencode example; would replace `qwen3:8b` across small tiers). |
94 | 97 |
|
95 | 98 | ### P2 (next up) |
96 | 99 |
|
97 | | -- **Bucket A — capture the research in `docs/models.md`.** Add the Ollama VRAM-tiering citation (the num_ctx default is now codified: `<24GiB → 4k`, all etude tiers in that bucket; Ollama recommends ≥64k for agents) and a short "how we vet model picks" note pointing at BFCL V4 (state-based agentic eval). Quick, machine-independent, banks the research before it goes stale. Bump `Last reviewed`. |
| 100 | +- **Bucket A — partially done in #07.** The Ollama VRAM-tiering citation and the ≥64k recommendation are in `docs/models.md` and `docs/hardware-tiers.md`. Still open: a "how we vet model picks" note pointing at BFCL V4 (re-verify before citing). |
98 | 101 | - **RTX 5080 PC / Windows install** (gpu-16gb tier). Hardware-gated — needs the PC. Exercises the `gpu-16gb` templates (`qwen3-coder:30b-32k` daily, `qwen3:8b-32k` speed), the unverified `install-windows.md` prose, and the `etude` launcher on a non-Mac surface (the macOS-specific bits — `open -a Ollama`, `brew --cask` — need Windows branches). **Fold in Bucket B:** evaluate Devstral Small 2 24B (`devstral-small-2:24b`, 15GB Q4, purpose-built for agentic coding) head-to-head against the current picks via the README→SUMMARY tool-calling test. |
99 | | -- **Rewrite `docs/install-macos.md`** — 133 lines of outdated brew-formula speculation, no variant-tag mention. Best after a second tier is verified. |
| 102 | +- ~~**Rewrite `docs/install-macos.md`**~~ — done in #07, rewritten around `install.sh` with the variant step in the manual path. |
100 | 103 | - **Build `install.sh --refresh` mode** — detect sidecar, diff vs current TSV, rebuild variants at the current `context` column, rewrite config. (When this lands, `etude` should call it directly instead of printing "re-run ./install.sh" after an etude-self update that changed tiers.tsv.) |
101 | 104 | - Flesh out `docs/usage.md` further — *partially done in #06 (added the `etude` section + `Last reviewed` bump);* still want day-to-day patterns, mode switching, real examples, and the `-<N>k` suffix explainer. |
102 | 105 | - Capture LAN-serve latency numbers (Air → desktop). LAN peers need install.sh or a manual `ollama create` for variant tags to resolve. |
103 | | -- Rewrite `install-windows.md` alongside the PC session. |
| 106 | +- Verify `install-windows.md` on the PC (rewritten in #07 but never run). |
104 | 107 | - Watch the Gemma 4 E4B tool-calling bug; flip `reliability` `watching → good` in `tiers.tsv` once fixed upstream, then verify it survives the variant pattern. |
105 | 108 |
|
106 | 109 | ### Upcoming sessions |
@@ -138,6 +141,15 @@ Conditional: if next session is on the PC, #3 jumps ahead of #1/#2 (it's the har |
138 | 141 |
|
139 | 142 | ### Complete (recent) |
140 | 143 |
|
| 144 | +### Session #07 — Public kit refresh (2026-10-13) |
| 145 | +- **Research** (primary sources): Ollama latest 0.40.3, default context still 4k under 24GiB, Ollama's opencode guide uses the same `@ai-sdk/openai-compatible` → `/v1` path etude does. opencode latest 1.19.0 (auto-update removed; OpenCode 2 behind `--major`). Every tag checked against ollama.com tag pages. |
| 146 | +- **Fixed dead references:** `qwen3-coder-next:80b` (never existed → `:q4_K_M`, 52GB), `glm-5:cloud` and `kimi-k2.5:cloud` (retired → `glm-5.3:cloud`, `kimi-k3:cloud`) across all 9 templates; drifted sizes. |
| 147 | +- **Watchlist:** newer models added as `watching` rows (shown by detect-tier, never offered by install). Verified picks unchanged; nothing could be re-tested (author's Mac has no models, disk space). |
| 148 | +- **`test.sh` Level 5 timeout** (portable background+deadline, `ETUDE_L5_TIMEOUT`), verified with stub opencode. The 12.5h hang is upstream (anomalyco/opencode#38723). |
| 149 | +- **`etude`** offers opencode updates only within the installed major (guards against OpenCode 2 nagging); 5 new tests pass. **Installer** closing message now says to open a new terminal and start with `etude`. |
| 150 | +- **Docs:** `install-macos.md` and `install-windows.md` rewritten (Windows marked unverified, variant step added, wrong template filename fixed, LAN no-auth warning); `models.md`, `hardware-tiers.md`, `usage.md`, README refreshed. |
| 151 | +- **Known:** `test-etude.sh`'s dry-run integration check fails on this Mac only because no model is installed. |
| 152 | + |
141 | 153 | ### Session #06 — Stack re-eval + `etude` front door (2026-06-03/04) |
142 | 154 | - **Stack re-evaluated** (deep-research pass): keep Ollama + opencode + Qwen3-Coder-30B; the num_ctx variant pattern is *vindicated* by Ollama's own VRAM-tiering docs (all etude tiers fall in the 4k bucket; Ollama recommends ≥64k for agents). Devstral Small 2 24B is the one new candidate to evaluate; BFCL V4 noted as a vetting method. opencode under heavy active maintenance (v1.15.x) — no harness switch. |
143 | 155 | - **`etude` front-door command shipped** — brainstorm → spec → 13-task TDD plan → built subagent-driven w/ layered review → merged to main + pushed (17 commits). Health check + throttled offline-safe drift check (opencode/ollama/etude) + glass-box updates + `exec opencode` handoff. Sourceable; on PATH via install.sh symlink; test.sh Level 6 + `test-etude.sh`. Spec/plan in `docs/superpowers/`. |
|
0 commit comments