@lardexx/arenacode 0.0.0-stage → 2.5.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arenacode contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,289 @@
-# Temporary Holding Version
+# arenacode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Terminal client for **ArenaCode** — a full-screen TUI (or a plain CLI, when you prefer) that talks to an
+[arena-bridge](https://github.com/) over HTTP, streams the Agent Mode timeline, and executes on your own machine
+the actions the agent asks for (terminal commands, file operations, plan approval, files the agent sends back).
+
+It is a Node port of the ArenaCode 2.5.2 desktop client (`ArenaCode-x64.exe`): same wire protocol, same `meta`
+payload, same local cards. **The bridge is untouched** — this is a client only, so it works with any existing
+`arena-bridge` 2.5.x (Python) instance, local or exposed through a tunnl.gg URL.
+
+```
+you ──▶ arenacode CLI ──▶ arena-bridge ──▶ agent
+        (this package)      (unchanged)     (Arena, or any agent on agentctl)
+```
+
+## Install
+
+```bash
+npm install -g arenacode
+arenacode --version           # 2.5.2
+```
+
+Or without installing:
+
+```bash
+npx arenacode ask "list the files in my folder"
+```
+
+Requires Node.js 18 or newer. No runtime dependencies.
+
+## Terminal UI
+
+The interface is a copy of [opencode](https://opencode.ai)'s TUI — same screen shape, same widgets, same keybinds —
+driving this bridge instead of an LLM provider. Nothing was approximated from screenshots alone: the layout was
+rebuilt from opencode 1.19.5's own source (`packages/tui/src/component/prompt`, `routes/session`, `ui/dialog`,
+`logo.tsx`, `theme/assets/*.json`) and checked against frames captured from the installed binary in a pty.
+
+```bash
+arenacode            # opens the TUI (the default when stdout is a terminal)
+```
+
+Home screen — two-tone block wordmark, centred prompt, tips, folder and version in the footer:
+
+```
+                            ▄
+        █▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀█ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
+        █  █ █▀▀▄ █▀▀▀ █  █ █  █ █    █  █ █  █ █▀▀▀
+        ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀
+
+                          /connect bridge offline at http://127.0.0.1:9
+              ┃
+              ┃  Ask anything… "Read package.json and add a lint script"
+              ┃
+              ┃  Build · arenacode bridge 2.5.2
+              ╹▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+                                                tab agents  ctrl+p commands
+
+                                  ● Tip Press ctrl+p for every command
+
+  ~/progetto                                                                                     v2.5.2
+```
+
+A session — user blocks on a `┃` border, assistant parts indented three cells, tool calls as `$ command` cards,
+`▣ Build · model · 1.2s` when the turn ends, `esc interrupt` while it runs:
+
+```
+  ┃
+  ┃  read hello.txt and run a command
+  ┃
+     ⠹ Thinking: Looking at the folder
+  ┃
+  ┃  → Reading file: hello.txt (23 B)
+  ┃  hello from the project
+  ┃
+  ┃  $ echo from-pc (exit 0)
+  ┃  from-pc
+  ┃
+     ▣ Build · arenacode · 0.4s
+  ┃
+  ┃  Ask anything… "Summarise what this project does"
+  ┃
+  ┃  Build · arenacode bridge 2.5.2
+  ╹▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+                                                         tab agents  ctrl+p commands
+  ~/progetto                                                                     4cabe1 · v2.5.2
+```
+
+Real frames captured from a pty, colours included — as rendered images
+[home](docs/tui-home.png) · [a session](docs/tui-session.png) · [the palette](docs/tui-palette.png),
+and as HTML snapshots [home](docs/tui-home.html) · [session](docs/tui-preview.html) ·
+[palette](docs/tui-palette.html) · [slash commands](docs/tui-slash.html) ·
+[confirm dialog](docs/tui-approve.html) · [plan approval](docs/tui-plan.html).
+How the copy is built and tested: [`docs/TUI.md`](docs/TUI.md).
+
+**Keys** (opencode's defaults, leader is `ctrl+x`):
+
+| Key | Action |
+|---|---|
+| `enter` | send · `shift+enter` newline |
+| `esc` | interrupt the turn · clear the input · quit |
+| `tab` | switch agent ↔ plan |
+| `ctrl+p` | command palette (`↑↓` select, `enter` run, `esc` close) |
+| `/` | slash commands with an inline list above the prompt |
+| `@file` | attach a file from the open folder |
+| `!command` | run a command locally |
+| `↑` / `↓` | prompt history (or move through the slash list) |
+| `pgup` / `pgdn` | scroll the transcript |
+| `ctrl+x` then | `q` quit · `n` new session · `l` task queue · `t` theme · `d` tool output · `b` sidebar · `s` stop |
+| `ctrl+c` | interrupt, then quit |
+
+**Dialogs.** Local actions open opencode-shaped dialogs — panel background, title on the left, `esc` on the right,
+the selected row painted in the primary colour, hints underneath: `Run once / Don't run` for terminal commands,
+`Approve / Reject / Revise` for the agent's plan, and file operations reported back to the bridge. `--yes` skips the
+terminal confirmation, `--confirm-writes` adds one for writes and removals.
+
+**Themes.** `ctrl+x t` cycles five palettes lifted from opencode's theme assets:
+`arenacode` (opencode's peach accent), `tokyonight`, `catppuccin`, `gruvbox`, `nord`.
+
+## Quick start
+
+```bash
+# 1. point the client at your bridge (URL + API key come from the bridge's runtime/connection.txt)
+arenacode init
+
+# 2. open the TUI in the folder you want the agent to work on
+arenacode --folder ~/progetto
+
+# 3. or stay in the plain CLI
+arenacode ask "read package.json and add a lint script"
+arenacode chat
+```
+
+`init` saves the URL, the API key and the open folder, then tests `/health` and `/auth/check` so you know the
+bridge accepts the key before you send anything.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `arenacode init` | configure URL, API key and open folder; test the connection |
+| `arenacode config [show\|path\|set <k> <v>\|clear]` | read or change the saved configuration |
+| `arenacode ping` | `/health` + `/auth/check`: version, public URL, queue, key |
+| `arenacode doctor` | local checks: node, platform, folder, git, bridge, API key |
+| `arenacode` (no args) | full-screen TUI — the default on a terminal |
+| `arenacode ui` | full-screen TUI, explicitly |
+| `arenacode ask "<instruction>"` | one task, streamed timeline, exit when it finishes |
+| `arenacode chat` | interactive session (`/help` shows the in-session commands) |
+| `arenacode stop [task-id]` | Stop: cancels the turn and the queued tasks on the bridge |
+| `arenacode handshake` | vision/handshake check task, like the client's |
+
+**Inspect the bridge**
+
+| Command | What it does |
+|---|---|
+| `arenacode tasks [state]` | task queue (`all`, `claimable`, `pending`, `claimed`, `done`, `error`) |
+| `arenacode status <task-id>` | state, claimant, result of one task |
+| `arenacode events <task-id>` | replayed timeline of a task |
+| `arenacode files [path]` | bridge workspace listing (`GET /fs`) |
+| `arenacode cat <path>` | preview a text file in the bridge workspace (`GET /file`) |
+| `arenacode attach <file…>` | upload files into the bridge workspace (`POST /upload`) |
+
+**Options**
+
+| Flag | Meaning |
+|---|---|
+| `--folder <dir>` | open folder: the project the agent reads and edits |
+| `--url <url>` / `--key <key>` | override the saved bridge settings |
+| `--mode agent\|plan` | task mode (default `agent`) |
+| `--lang it\|en\|es` | language for prompts and cards (default `it`) |
+| `--no-pc` | tell the agent `pc_access: false` (no terminal on this PC) |
+| `--yes` | run local commands without asking |
+| `--confirm-writes` | ask before `write` / `replace` / `rm` / `mv` in your folder |
+| `--attach a,b` | upload files together with the task |
+| `--idle-timeout <s>` | close the session after N idle seconds (default 180, like the desktop client) |
+| `--json` | raw JSON output where available |
+
+## What runs on your machine
+
+The agent never touches your PC directly: it asks, and this client shows a card. With `--yes` (or by pressing
+`r`) the card is executed locally and the result goes back to the bridge.
+
+| Card | Source | Executed here |
+|---|---|---|
+| **terminal** | `POST /task/<id>/local-exec` | PowerShell / `cmd` / WSL on Windows, `/bin/sh` elsewhere — asked before running unless `--yes` |
+| **files** | `local-fs` | `ls`, `stat`, `read`, `write`, `replace`, `find`, `mkdir`, `mv`, `rm`, `pull`, `git_status`, `git_log`, `git_diff`, `git_commit`, `git_revert`, `git_publish` |
+| **plan** | `local-ui` `plan` | approve / reject / ask for a revision, right in the terminal |
+| **file from the agent** | `local_file` | downloaded from `GET /file?raw=1` into the open folder |
+| **wait / sysinfo** | `local-ui` | sleeps, or reports the local machine |
+
+Every file path is resolved **inside the open folder**; paths that escape it are refused. `rm` refuses to delete
+the folder itself. Local operations run with your user's permissions — `--confirm-writes` adds a confirmation for
+mutating file operations, `--yes` skips confirmations for terminal commands.
+
+### Not available in a terminal
+
+The desktop client can drive the whole PC (mouse, keyboard, screenshots, app launching — `local-ui`
+`control` / `type` / `keystroke` / `screenshot` / `app` / `state` / `apps` / `multi_*`). A terminal cannot, so
+those cards are answered with an explicit error instead of silently doing nothing:
+
+```json
+{ "ok": false, "error": "operation \"screenshot\" is not available in the terminal client: the ArenaCode desktop client is required" }
+```
+
+Everything else in the protocol is implemented.
+
+## How it talks to the bridge
+
+Same requests as the desktop client (see [`docs/ANALYSIS.md`](docs/ANALYSIS.md) for the reverse-engineered
+details):
+
+```
+POST /task
+{"instruction":"[ArenaCode mode: agent]\n…","wait":0,
+ "meta":{"client":"ArenaCode 2.5.2","os":"…","lang":"it","policy":"…","pc_access":true,
+         "git":{"available":true,"repo":true,"branch":"main"},
+         "workspace":{"root":"…","cwd":"…","shell":"…","pwsh7":false,"powershell":false,"wsl":false,
+                      "active_file":"","selection":"","selection_line":0,"open_files":[],
+                      "top_level":["src/","package.json"],"tools":{"git":true,"node":true}}},
+ "agent_prompt":"…",              // the client's built-in prompt, sent with every task
+ "project_context":"…"}           // content of context_<project>.md, when present
+
+GET  /task/<id>/events?format=json&since=<cursor>&wait=25    ← timeline (long-poll)
+POST /task/<id>/local-result    {"rid":"lx-…","output":"…","code":0}
+POST /task/<id>/cancel                                     ← Stop
+GET  /auth/check                                           ← key valid on this PC
+```
+
+Headers: `Authorization: Bearer <API key>`, `X-Arena-Device: <machine id>`, `Content-Type: application/json`.
+The device header is what binds an API key to one PC (`403 device_mismatch` if it is already bound elsewhere:
+release it on the bridge with `keys unbind <ID>`).
+
+## Configuration
+
+`arenacode config path` prints the file:
+
+* Windows — `%APPDATA%\ArenaCode\config.json`
+* macOS / Linux — `~/.arenacode/config.json`
+
+```json
+{
+  "url": "https://nome-del-bridge.tunnl.gg",
+  "key": "arn_…",
+  "folder": "/home/me/progetto",
+  "lang": "it",
+  "mode": "agent",
+  "pc_access": true,
+  "device": "",
+  "vision": false,
+  "idle_timeout": 180
+}
+```
+
+The file is written with mode `0600`. The desktop client stores the key encrypted with Windows DPAPI; a portable
+Node client cannot, so the key sits in that file — keep it readable only by you, and use a dedicated API key
+(`arenacode keys` on the bridge side: `python3 bridge_server.py keys create "laptop CLI"`).
+
+Environment variables override the file: `ARENACODE_URL`, `ARENACODE_KEY`, `ARENACODE_FOLDER`,
+`ARENACODE_CONFIG`.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `auth failed: unauthorized` | wrong API key — `arenacode config set key <key>` (from `runtime/connection.txt`) |
+| `403 device_mismatch` | key bound to another PC — on the bridge: `python3 bridge_server.py keys unbind <ID>` |
+| `bridge unreachable` | tunnel down or wrong URL — check `arenacode ping`, and `/health` on the bridge |
+| agent never answers | the agent is not listening: run `bash listen.sh` in the bridge folder |
+| everything hangs after a turn | `--idle-timeout` closes the session; check `arenacode status <id>` |
+
+## Development
+
+```bash
+npm test              # CLI integration: real Python bridge + fake agent
+SCENARIO=approve node test/tui.js   # TUI, terminal card confirmation
+SCENARIO=plan node test/tui.js      # TUI, plan approval
+node test/tui.js      # TUI: drives the real pty, checks the rendered frames
+node tools/frame2html.js /tmp/tui-frames.raw docs/tui-preview.html --match done   # frame -> HTML snapshot
+```
+
+The integration test spins up `bridge_server.py` from a private copy, runs a fake agent that claims the task,
+then checks that the CLI answered the `local-fs` / `local-exec` cards with the right payloads, applied the file
+write, rendered the timeline and bound the API key to the device.
+
+Set `BRIDGE_DIR` to point at the bridge sources if they are not in `/home/user/bridge_extract/bridge`, and
+`VERBOSE=1` to see bridge logs.
+
+## License
+
+MIT.

package/bin/arenacode.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+
+// Piping into `head`/`less` closes stdout early: that is not an error.
+process.stdout.on('error', (e) => {
+  if (e && e.code === 'EPIPE') process.exit(0);
+  throw e;
+});
+
+// Exit explicitly: undici keeps keep-alive sockets open, which would keep the
+// process alive after the turn is finished.
+main(process.argv.slice(2))
+  .then((code) => process.exit(typeof code === 'number' ? code : 0))
+  .catch((e) => {
+    process.stderr.write(`arenacode: ${e && e.stack ? e.stack : e}\n`);
+    process.exit(1);
+  });

package/docs/ANALYSIS.md

@@ -0,0 +1,201 @@
+# Reverse-engineering notes — `ArenaCode-x64.exe` (2.5.2)
+
+What this document is: the evidence behind the port. Every claim about the desktop client's behaviour below is
+backed by a static observation on the binary, the strings it embeds, or the payloads the bridge expects. Nothing
+here was obtained by running the executable (it is a Windows GUI binary; the analysis host is Linux).
+
+## 1. Target
+
+| | |
+|---|---|
+| File | `ArenaCode-x64.exe` (inside `arenacode-x64.zip`, 1.85 MB zip / 5 372 416 B exe) |
+| SHA-256 | `1be348946c5c101a0122941c9c1b0c48b831138b8bbc98ac9c6eba66ba6e9c54` |
+| Format | PE32+ executable, x86-64, 10 sections, stripped to external PDB |
+| Toolchain | MinGW/GCC + MSVCRT (`__wgetmainargs`, `_beginthreadex`, `mingw` style imports), Win32 GUI subsystem |
+| Manifest | `<assemblyIdentity version="2.5.2.0" … name="ArenaCode" type="win32"/>` |
+| Entropy | 6.30 file-wide (max block 6.40) → **not packed, not encrypted** |
+| TLS | 3 callbacks in `.text` (`0x140135c80`, `0x140135c50`, `0x140148ea0`) — normal MinGW runtime setup |
+
+## 2. How it was analysed
+
+[REA](https://github.com/morluto/rea) 6.8.0 (`rea-agents` on npm), run with Node 22.23.4 — provider-free static
+commands, since no Ghidra/Hopper/IDA instance was available for decompilation on this host:
+
+```bash
+rea doctor                                                # provider audit (no native engine present)
+rea inspect-pe-imports     ArenaCode-x64.exe --format json # ev_51542780…583e
+rea inspect-byte-entropy   ArenaCode-x64.exe --format json # ev_aca82405…eb14
+rea inspect-pe-load-config ArenaCode-x64.exe --format json # ev_3d8aab65…1339
+```
+
+Deep decompilation (`rea analyze`, `rea decompile`) failed closed with `provider_unavailable`: it needs
+`GHIDRA_INSTALL_DIR` / Hopper / IDA. That is why the reconstruction below rests on imports, embedded wide
+strings and the payload contract rather than on pseudocode. For a C/GUI client that is enough: the interesting
+surface is the HTTP layer and the JSON it builds, and both are visible as literal format strings.
+
+## 3. What the binary is
+
+A Win32 GUI client (USER32 + COMCTL32 + GDI32/GDI+ widgets, `GetOpenFileNameW`, `SHBrowseForFolderW`,
+drag-and-drop) that
+
+* keeps its state in `%APPDATA%\ArenaCode\` — `config.ini`, `sessions\`, `chats\`;
+* talks HTTPS to an **arena-bridge** with **WinHTTP** (`WINHTTP.dll`: `WinHttpOpen`, `WinHttpOpenRequest`,
+  `WinHttpSendRequest`, `WinHttpReadData`, …) plus `WS2_32` for sockets;
+* executes things locally with `CreateProcessW` (+ `PeekNamedPipe`, `CreatePipe`), `ShellExecuteW`,
+  `\\WindowsPowerShell\\v1.0\\powershell.exe`;
+* protects the stored API key with **DPAPI**: `CRYPT32.dll!CryptProtectData` / `CryptUnprotectData`, stored as
+  `secret_dpapi`;
+* identifies the machine with `HKLM\SOFTWARE\Microsoft\Cryptography\MachineGuid` (`ADVAPI32` registry +
+  `SystemFunction036` = `RtlGenRandom`);
+* carries a bundled CA store (curl's `ca-bundle.crt`) and a runtime-DLL loader (`LoadLibraryW`/`GetProcAddress`)
+  for the optional `windows-use` automation DLL — the binary contains the message *"windows-use DLL not
+  embedded in the program"*.
+
+String evidence (wide strings, file offset ≈ `0x22b108` onward for the prompt):
+
+```
+%s\%s\config.ini            %APPDATA%\ArenaCode\config.ini
+MachineGuid                 SOFTWARE\Microsoft\Cryptography
+secret_dpapi                sessions  chats
+User-Agent: ArenaCode/1.0   application/json
+Content-Type:               Authorization: Bearer      X-Arena-Device:
+```
+
+## 4. HTTP protocol (as the client sends it)
+
+| Method | Path | Body |
+|---|---|---|
+| POST | `/task` | `{"instruction":"…","wait":0,"meta":{…},"agent_prompt":"…","project_context":"…"}` |
+| GET | `/task/<id>/events?format=json&since=<cursor>&wait=25` | — (long-poll timeline; fields `events`, `next`, `done`) |
+| GET | `/task/<id>/events?since=0&follow=1` | — (SSE fallback, `Accept: text/event-stream`) |
+| POST | `/task/<id>/local-result` | `{"rid":"…","output":"…","code":0}` |
+| POST | `/task/<id>/local-state` | `{"allow":true\|false}` — terminal consent |
+| POST | `/task/<id>/user-event` | `{"kind":"reject","path":"…"}` |
+| POST | `/task/<id>/cancel` | `{}` — Stop |
+| GET | `/task/<id>/ui-payload/<rid>` | — (text typed by a `local-ui type` step, delivered once) |
+| GET | `/health`, `/auth/check` | — (version check, key valid on this PC) |
+| GET | `/fs?path=`, `/file?path=&raw=1` | — (bridge workspace preview) |
+| POST | `/upload?path=` | raw bytes (`application/octet-stream`) |
+
+`meta`, exactly as the client serialises it:
+
+```json
+{"client":"ArenaCode 2.5.2","os":"…","lang":"it",
+ "policy":"work_directly_on_pc: read and edit files in the open folder on the PC, also for existing projects; …",
+ "pc_access":true,
+ "git":{"available":true,"repo":true,"branch":"main"},
+ "workspace":{"root":"…","cwd":"…","shell":"…","pwsh7":false,"powershell":true,"wsl":false,
+              "active_file":"","selection":"","selection_line":0,
+              "open_files":[],"top_level":[],"tools":{}}}
+```
+
+Task framing: `instruction` starts with a mode line — `[ArenaCode mode: agent]`, `[ArenaCode mode: plan]`,
+`[ArenaCode mode: computer-agent]`, or `[ArenaCode handshake] …` — followed by the mode paragraph and the user's
+text. Plan approval answers come back through `local-result` as
+`{"ok":true,"approved":true}`, `{"ok":false,"approved":false}` or
+`{"ok":false,"approved":false,"revise":true,"feedback":"…"}`.
+
+## 5. Embedded agent prompt
+
+The client embeds its whole system prompt (33 147 characters, UTF-16LE at ≈`0x22b108`) and ships it with every
+task as `agent_prompt`; the bridge writes it to `runtime/agent_instructions.txt` on the first task after a start.
+The port sends the same text byte-for-byte: [`src/prompts/agent-prompt.md`](../src/prompts/agent-prompt.md)
+(extracted with `strings -e l` + a UTF-16 decode around the marker `# ArenaCode agent: system prompt`).
+
+That prompt doubles as protocol documentation from the agent's side: it lists the `agentctl` commands, the IDE
+vs Computer Agent modes, the git rules, the vision handshake (`vision-png`,
+`--has-vision-enabled:true|false`) and the "closing a task" contract (`context_<project>.md`).
+
+## 6. Local card types the client must execute
+
+| Event field | Ops | Executed by |
+|---|---|---|
+| `local_exec` | `command`, `cwd`, `shell` = `powershell` \| `cmd` \| `wsl`, `admin` (UAC), `sandbox_reason` | `CreateProcessW` + pipes; card shows *"Command not run: rejected by the user"* (`code -1`) when declined |
+| `local_fs` | `ls`, `stat`, `read`, `write`, `replace`, `mkdir`, `mv`, `rm`, `pull`, `find`, `git_status`, `git_log`, `git_diff`, `git_commit`, `git_revert`, `git_publish` | in-process file APIs + `git` CLI; the result is a JSON document returned as `output` |
+| `local_ui` | `plan`, `control`, `type`, `keystroke`, `screenshot`, `app`, `state`, `sysinfo`, `apps`, `wait`, `multi_select`, `multi_edit` | GUI automation (`windows-use` DLL) + the Accept/Reject approval cards |
+| `local_file` | `remote`, `name`, `dest` | `GET /file?raw=1` → write into the open folder |
+
+Event shapes on the timeline: `thought`, `tool` (with `icon`, `state`, `secs`, `detail`), `text` (with `delta`),
+`status`, `vision` (`{"vision":bool}`), `user` (`{"kind":"reject","path":"…"}`), `done`.
+
+## 7. What the port reproduces, and what it cannot
+
+| Desktop client behaviour | `arenacode` (this package) |
+|---|---|
+| WinHTTP + bearer key + `X-Arena-Device` (MachineGuid) | `fetch` + same headers; device id from the registry on Windows, `/etc/machine-id` elsewhere |
+| `POST /task` with `meta` / `agent_prompt` / `project_context` | identical payload (see `src/meta.js`) |
+| Long-poll timeline, mode-line framing, `wait: 0` | identical (`src/turn.js`) |
+| `local-exec` with PowerShell/cmd/WSL and refusal payload | same, with `r`/`d` confirmation (`src/local.js`) |
+| `local-fs` ops incl. git, JSON result contract | same operations, same JSON keys |
+| Plan approval / revision / `wait` / `sysinfo` cards | same |
+| mouse, keyboard, screenshots, app launch, UIA element dumps | **not possible from a terminal** — answered with an explicit `{"ok":false,"error":"…"}` |
+| DPAPI-encrypted `secret_dpapi` in `config.ini` | JSON config, mode `0600` (a portable client has no DPAPI) |
+| GUI session/chat list, drag-and-drop, tray | out of scope; history stays on the bridge (`/tasks`, `/task/<id>`) |
+
+## 8. Reproducing the analysis
+
+```bash
+# REA (needs Node ≥ 22.19; no analysis engine required for the commands below)
+npx -y rea-agents@latest doctor
+npx -y rea-agents@latest inspect-pe-imports ArenaCode-x64.exe --format json
+npx -y rea-agents@latest inspect-byte-entropy ArenaCode-x64.exe --format json
+
+# protocol strings (the client stores them as UTF-16LE)
+strings -a -e l -n 4 ArenaCode-x64.exe | grep -E '^/(task|health|events|file|fs|upload)|Authorization|X-Arena'
+
+# the embedded system prompt, byte-exact
+python3 - <<'PY'
+data = open('ArenaCode-x64.exe','rb').read()
+i = data.find('# ArenaCode agent: system prompt'.encode('utf-16le'))
+end = i
+while data[end:end+2] != b'\x00\x00':
+    end += 2
+print(data[i:end].decode('utf-16le'))
+PY
+```
+
+## 9. Deep analysis with Ghidra
+
+REA's provider-free commands (section 2) reconstruct the protocol surface, but the decompiler is what turns
+"these strings exist" into "this function builds this request". Setup on this host, and what it cost:
+
+| Step | Result |
+|---|---|
+| Ghidra **12.2** + Temurin JDK 21, `GHIDRA_INSTALL_DIR` set | provider refused it: `unsupported_version` — REA 6.8.0 accepts the **12.1.x** line (verified with 12.1.4) |
+| Ghidra **12.1.4**, `MAXMEM=1300M`, 5 min deadline | killed by the kernel OOM killer (`resource_constraint`): the container has 2 GB and Ghidra forks one native decompiler per CPU |
+| Ghidra **12.1.4**, `taskset -c 0`, `MAXMEM=900M`, 30 min deadline | **succeeded** — `ev_63854c5644837a356103bc1033918e6946018a8bacd457b1256a8b911a309d0f` |
+
+The successful import + analysis of the 5 MB image reports:
+
+```
+document         target-1be348946c5c.exe
+image_base       0x140000000
+segments         11
+procedure_count  6376
+string_count     5260
+provider         rea-workflow / ghidra 12.1.4
+```
+
+### What it changes about the port
+
+Nothing in the wire format: every field in section 4 had already been confirmed by running the port against a real
+bridge. What it changes is *where to look next*. `rea decompile --file-offset` on a string's offset does **not**
+land inside a procedure — string literals live in `.rdata`, so the useful move is procedure-name search plus
+decompiling the callers of `WinHttpOpenRequest`, which is the next step if the port ever needs the internals:
+
+1. the exact `local-fs` JSON response shapes — currently written against the consumer contract in `agentctl.py`
+   and verified empirically;
+2. the Accept/Reject card state machine (file-change cards and `user-event` on reject);
+3. the `windows-use` DLL ABI behind `local-ui` mouse/keyboard actions.
+
+None of these block a working client: (1) is implemented and tested end to end, (2) has a terminal-appropriate
+equivalent (`--confirm-writes` + the confirm modal), and (3) is answered with an explicit
+"not available in the terminal client" error, which is what the protocol expects from a client that cannot drive
+a GUI.
+
+### Practical note
+
+Decompiling a GUI client is the expensive path and usually the wrong first one. For a program whose interesting
+behaviour is `WinHttpOpenRequest` plus `swprintf` of JSON, **the literals are the specification**. The eight
+sections above were reconstructed with zero decompilation, deterministically, in minutes; the Ghidra run cost
+about 25 minutes of a single core to add an inventory, not new protocol facts.

package/docs/PUBLISHING.md

@@ -0,0 +1,65 @@
+# Publishing
+
+The package is ready: `arenacode@2.5.2`, 23 files, ~60 kB tarball, no runtime dependencies.
+
+```bash
+cd arenacode-cli
+npm publish --dry-run     # + arenacode@2.5.2
+```
+
+## Status of the publish attempt
+
+| Attempt | Result |
+|---|---|
+| `npm whoami` with the supplied token | ✅ authenticated as `lardexx` |
+| `npm view arenacode version` | ✅ 404 → the name `arenacode` is free |
+| `npm publish` (unscoped `arenacode`) | ❌ `403 Forbidden — You may not perform that action with these credentials.` |
+| `npm publish` (`@lardexx/arenacode`, public) | ❌ same 403 |
+
+A 403 on PUT with a token that authenticates fine means the token itself is not allowed to write. Three usual
+causes, in order of likelihood:
+
+1. **The token is read-only.** Granular tokens have a *Permissions → Read and write* switch; the default in some
+   flows is read-only. Create a new one with **Read and write** and package access **All packages**.
+2. **The token is restricted to existing packages.** A granular token limited to a selection of packages cannot
+   create a *new* package name: pick “All packages”.
+3. **The account requires 2FA for publishing.** Then `npm publish --otp=<code>` (or an interactive
+   `npm login` + `npm publish`) is needed; automation tokens must be created with the *bypass 2FA* option.
+
+## Commands
+
+```bash
+# A. with a fresh token that can write
+npm login                                    # or: npm config set //registry.npmjs.org/:_authToken=<token>
+npm publish                                   # unscoped: arenacode
+
+# B. with the tarball
+npm publish arenacode-2.5.2.tgz
+
+# C. under your scope (always available to your account)
+node -e "const p=require('./package.json');p.name='@lardexx/arenacode';p.publishConfig={access:'public'};require('fs').writeFileSync('package.json',JSON.stringify(p,null,2)+'\n')"
+npm publish --access public
+```
+
+The `bin` stays `arenacode` in all three cases, so the installed command is the same:
+
+```bash
+npx arenacode          # or npx @lardexx/arenacode
+```
+
+## Checklist before publishing
+
+- [x] `npm pack --dry-run` clean, no stray files (`test/`, `tools/` are excluded by the `files` field)
+- [x] `npm test` green (bridge + fake agent + CLI)
+- [x] `node test/tui.js` green (real pty, rendered frames)
+- [x] `LICENSE` (MIT), `README.md`, `docs/`
+- [ ] version policy: `2.5.2` tracks the ArenaCode client it ports; use `2.5.3`/`2.6.0` afterwards, and keep the
+      client number in `src/config.js` (`VERSION`) in sync
+
+## After publishing
+
+```bash
+npm view arenacode version dist.tarball
+npm install -g arenacode
+arenacode doctor
+```