neuron/FISHBONE.md

# Fishbone: black TUI, split starts, leftover OpenCode

Fix **bottom to top**. Do not start at “blank screen” or a new `script/dev.ts`. Each layer can look like the same black window.

Date: 2026-08-24  
Repo: `neuron`  
Kit: sibling `neuron-tui`  
Symptom: iTerm looks empty after launching the CLI, or the CLI dies before that with a loud error.

---

## Unproven (do not skip)

We have **not** shown that a high-contrast cell landed in **your** iTerm **alternate screen** on the current command.

iTerm “session contents” (AppleScript) is usually the **main** buffer. The TUI draws on the **alt** buffer. Empty contents is not proof of a blank app.

Until a bright first frame or a dump of the renderer buffer, “always blank” is several failures wearing one coat.

---

## Core lizard (cyclomatic)

Tool: **lizard** (CCN = cyclomatic complexity). Default warn is **15**. Run 2026-08-24 on `@neuron-tui/core` + native Zig.

**The JS presentation host is too big for lizard to see.** `renderer.ts` is 5130 lines. Lizard reports avg CCN **1.9** and **0 warnings**. That is a lie: it swallowed most of `CliRenderer` into `resolveModes` (595 lines). `zig.ts` is 6706 lines and lizard found **5 functions**. If a metric cannot split the file, the file is the problem.

Hand count of the JS hot path (if/else/switch + `&&`/`||`): `loop` ~32 branches / 122 nloc; `requestRender` ~10; `setupTerminal` ~14; `constructor` ~39. Not 1.9.

**Native is where lizard can see, and one function owns present:**

| CCN | nloc | fn | file |
|---|---|---|---|
| **189** | 394 | `prepareRenderFrameWithWriter` | `native/src/renderer.zig` |
| **104** | 240 | `checkEnvironmentOverrides` | `native/src/terminal.zig` |
| 58 | 107 | `processCapabilityResponse` | `terminal.zig` |
| 57 | 109 | `writeSnapshotCommit` | `renderer.zig` |
| 47 | 68 | `writeKittyImages` | `renderer.zig` |

`prepareRenderFrameWithWriter` is **12×** the warn line. It is the function that turns the JS buffer into TTY bytes. Skip lives next door: `prepareFrame` tryLock miss → `finishSkippedFrame` **clears** the buffer JS just drew. `renderer-output.zig` looks simple (avg CCN 2.6). The skip is small. The present is not.

JS outliers that are real parsers, not the blank path: `Markdown.createInitialStyledText` CCN **366** (lizard may have eaten the class), `toNativeAudioStreamFormat` 101, `parseAlign` 89, `parseKeypress` 84, `parsePositiveDecimalPrefix` 77.

**Fix from this list first:** split/log `prepareRenderFrameWithWriter`; do not wipe `nextRenderBuffer` on skip; do not run `checkEnvironmentOverrides` + alt-screen + first frame on the same mutex; split `CliRenderer` until lizard can name `loop` / `requestRender` / `setupTerminal`.

---

## Bottom → top (fix in this order)

### 0. Hold one test still

This chat mixed runs: Cursor aborted `serve`, AppleScript 0×0 windows, fake `script/dev.ts`, OpenTUI then `neuron-tui`, port 4096 leftovers. “Still blank” compared **different stacks**.

**Fix:** one command, real iTerm (not Cursor job), leave the engine alone, do not AppleScript-scrape alt-screen.

Current command (from any folder, including `~`):

```bash
bun --cwd /Users/will/Development/neuron-technologies/neuron/packages/cli --conditions=browser src/index.ts
```

`--cwd packages/cli` is required so `packages/cli/bunfig.toml` preloads `@neuron-tui/solid/preload`. That cwd also makes `process.cwd()` = `packages/cli` (the “project” the engine/TUI think you opened). That is a later layer.

---

### 1. Core: native library (`neuron-tui`)

**What:** Zig renderer. On darwin arm64 JS does `import("@neuron-tui/core-darwin-arm64")`.  
**Fact:** that name **404s on npm**. OpenTUI’s `@opentui/core-darwin-arm64` **is** published. Rename did not ship binaries.  
**Error (loud):** `Failed to initialize OpenTUI render library: Cannot find package '@neuron-tui/core-darwin-arm64'` — leftover **OpenTUI** string in **your** core.  
**Done locally:** workspace package `neuron-tui/packages/core-darwin-arm64` copies `packages/native/lib/aarch64-macos/libopentui.dylib` (built ~Aug 22). CLI/TUI depend on it.

**Still open:** JS is today; dylib is another day. ABI mismatch → black, **no** JS throw. Rebuild native from current `neuron-tui` when fixing core for real. Other platforms still 404 (linux/win optional deps).

---

### 2. Core: Mac thread vs Linux, skip vs fail

**What:** `CliRenderer` constructor sets `useThread: true` except **Linux** (forced off; comment: thread **crashes**). You are on Mac.

**Two output machines:**

| Path | What happens on native `render` status `SKIPPED` (1) |
|---|---|
| Tests / custom stdout | `NativeSpanFeed` → wait `feed.idle()` → retry |
| iTerm `process.stdout` + thread | **No feed.** `stdout.write` hijacked to `lib.writeOut`. Skip → `"backpressured"`, **no** `console.error` |

**Alt-screen** is `lib.setupTerminal(..., alternate-screen)` — wipe is **native**, before Solid has a tree.

**Fix direction:** `useThread: false` on darwin until skip is visible; or log skip; or use feed on TTY; rebuild native; prove `lib.render` returns presented not skipped.

---

### 3. Core: idle one-shot vs live loop

**What:** `@neuron-tui/solid` `render()` does `engine.attach` (timeline) + mount. Tests call `renderer.start()`. The **app does not**.

Paint is `requestRender()` → one `activateFrame` if `_isRunning` is false.

`activateFrame` **no-ops** if `updateScheduled` is already false.

`internalStart()` **clears** `updateScheduled` so queued one-shots die when the live loop starts. Idle shots and the continuous loop **cancel each other by design**.

**Fix direction:** `renderer.start()` (or `requestLive`) after mount so skipped frame 0 is not the only chance. Do not “fix” this by adding another wrapper script.

---

### 4. Core: queries and pixels on the same hijack

`setupTerminal` returns immediately. It has already:

1. switched alt-screen  
2. turned on capability probes (`privateCapabilityRepliesActive`)  
3. written those probes through **the same** `lib.writeOut` as frames  

iTerm replies on stdin. Frame 0 is `process.nextTick`. Probes and first paint **contend**. Skip on frame 0 is “queue full,” not “JS forgot to draw.” The 5s timer is **stop asking**, not **don’t draw yet**.

Constructor also replaces **global** `requestAnimationFrame`. If the renderer is idle, rAF UI sleeps too.

**Fix direction:** don’t probe on the presentation path; or don’t hijack stdout until after first present; or `useThread: false` so `stdout.write` is real TTY again.

---

### 5. Errors after core owns stdout can vanish

Loud errors you pasted (`Failed to start server`, `react`, missing dylib) happened **before** hijack.

Bootstrap (`sync.tsx`) uses `throwOnError: true` and `exit(e)` **after** the TUI is up. Those logs can go into Zig. **No `ERROR (#1)` + black ≠ no error.**

**Fix direction:** log bootstrap failures to a file, or restore `realStdoutWrite` for `console.error`.

---

### 6. `--conditions=browser` is a pun

**Needed:** `solid-js` client build (`dist/solid.js`), not `dist/server.js`.  
**Also:** Bun treats it as “browser app” → default JSX factory **React**.

`--cwd` **repo** skips `packages/cli/bunfig.toml` → no `@neuron-tui/solid/preload` → `Cannot find package 'react'`. Root bunfig preload failed: `@opentui/solid/preload` not installed at root (and that is not your kit).

**Fix direction:** keep CLI bunfig preload; do not put kit preload on repo root; or pass `--jsx-import-source @neuron-tui/solid` explicitly; split “solid client resolve” from “browser JSX.”

---

### 7. One `--cwd`, three jobs

| Job | Wants |
|---|---|
| bunfig / Solid preload | `packages/cli` |
| `process.cwd()` = project for engine/TUI | neuron repo (or the user’s real project) |
| Finding `src/index.ts` | a path that exists from **this** shell (`~` vs repo) |

`--cwd packages/cli` from `~` → ENOENT (`packages/cli` is relative).  
`--cwd` repo → JSX React.  
Old `script/dev.ts` climbed **twice** (`URL ..` then `dirname`) → `neuron-technologies/` not `neuron/`. Deleted; do not bring it back.

**Fix direction:** absolute CLI path + set process cwd to the repo **after** bun loads bunfig, or `bun --cwd cli` plus `NEURON_CWD` / engine `cwd` override. Never one relative `--cwd` for all three.

---

### 8. Two bosses for “is the engine up”

CLI daemon: alive = `~/.neuron/server.json` **and** `/global/health`.  
A live `bun ./src/serve.ts` on **4096** with **no** file = “no server.” Child spawn uses `stdio: ignore`. Wait → `Failed to start server`.

Daemon `start()` now probes default `http://127.0.0.1:4096` if registration is missing.

**Fix direction:** one authority (health on the port, or always `--register`). Never hide child stderr. Don’t spawn a second listener on 4096.

---

### 9. Painted empty ≠ unpainted

`packages/tui` is still OpenCode’s **client** (many HTTP routes, plugins, home layout). Neuron answers a lot with **empties** so the client won’t invent data.

Home: two `flexGrow={1}` spacers, 7-row logo, prompt. Wordmark PNG is cream on **black**; app clear `#0a0a0a`. `StartupLoading` only appears if `ready()` is false after 500ms; App `ready` starts **true** → **no spinner**.

A **successful** frame can look dead.

Settings `~/.local/state/opencode/kv.json` used to **hide the whole tree** until a flock lock finished (`createSimpleContext` + `Show when ready`). That gate was removed; file is optional. **Do not treat kv as the remaining blank.**

Logo `protocol="auto"` (Kitty/iTerm handshake) could hang with no ASCII fallback. Now `protocol="blocks"` on the same PNG. Contrast still terrible.

**Fix direction:** first frame **high contrast** (e.g. yellow “neuron” on black) **before** logo/image; `renderer.start()`; then put the wordmark back. Do not use alt-screen scrape as pass/fail.

---

### 10. Product vs kit (do not confuse)

| Piece | What it is |
|---|---|
| `neuron-tui` | Your **kit** (Zig + Solid reconciler). Not the Neuron chat app. |
| `packages/tui` | OpenCode **screens** now importing `@neuron-tui/*`. |
| `packages/cli` | Launcher + daemon; still `@opencode-ai/cli`. |
| `packages/neuron` | Engine HTTP on 4096. |
| `script/dev.ts` | Fake one-command runner. **Deleted. Do not restore.** |

Root `package.json` workspaces include sibling `../neuron-tui/packages/{core,solid,keymap,react,core-darwin-arm64}`. Nested workspace + npm 404s on other `core-*` platforms remain.

---

## Loud errors already explained (not “blank”)

| Paste | Cause |
|---|---|
| `Could not change directory to "packages/cli"` | Relative `--cwd` from `~` |
| `Failed to start server` | Daemon vs leftover 4096 / no `server.json` |
| `Cannot find package 'react'` | JSX default React; CLI bunfig not loaded |
| `preload not found "@opentui/solid/preload"` | Root bunfig; not your kit |
| `Cannot find package '@neuron-tui/core-darwin-arm64'` | Native never published; now local package |

---

## Not the user’s fault

Did not delete `packages/cli`. Did not need React. Did not “fail to use the TS build.” Bun/`package.json` already was that. Did not turn on a blank-screen mode.

---

## Suggested first patches (still bottom-up)

1. Rebuild `neuron-tui` native for this machine; keep `core-darwin-arm64` in workspace.  
2. In `packages/tui` `createCliRenderer`: `useThread: false` until skip is logged.  
3. After Solid `render()`, `renderer.start()`.  
4. First paint: high-contrast text, not the black wordmark.  
5. Then: one cwd story, engine health-only, bootstrap errors to a file.

When those five are true in **one** iTerm run, re-judge “blank.” Not before.