diff --git a/.plans/opencode-ai-cli-full-integration-plan.md b/.plans/archived/opencode-ai-cli-full-integration-plan.md
similarity index 100%
rename from .plans/opencode-ai-cli-full-integration-plan.md
rename to .plans/archived/opencode-ai-cli-full-integration-plan.md
diff --git a/.plans/opencode-fake-provider-direct-plan.md b/.plans/archived/opencode-fake-provider-direct-plan.md
similarity index 100%
rename from .plans/opencode-fake-provider-direct-plan.md
rename to .plans/archived/opencode-fake-provider-direct-plan.md
diff --git a/.plans/trap-sandbox-gateway-plan.md b/.plans/trap-sandbox-gateway-plan.md
new file mode 100644
index 0000000..23b105e
--- /dev/null
+++ b/.plans/trap-sandbox-gateway-plan.md
@@ -0,0 +1,217 @@
+# Plan: trap-sandbox gateway + trapos-sandbox client (first iteration)
+
+## Context
+
+`tools/trap-sandbox/` is a new TypeScript service that replaces the legacy `tools/mcp-bridge`
+(kept only for inspiration). It delivers a **general-purpose Fastify API on port 4444**, organized
+into "sandbox modules" (Fastify plugins). The only module in this iteration is the
+**`trapos-cloud-gateway`**: a WebSocket gateway giving a CraftOS (trapos) computer and the
+sandbox/opencode a generic, bi-directional request/reply protocol.
+
+On the Lua side, a new `trapos-sandbox` package installs `servers/sandbox.lua` (a boot daemon that
+owns one persistent WS connection and bridges WS frames to in-OS events) plus a `sandbox` command.
+The legacy `trapos-sandbox` package is renamed to `trapos-sandbox-legacy`.
+
+**Intended outcome:** after installing the new trapos and setting `sandbox.url`, running
+`sandbox health` in-game prints `sandboxOk: true` / `opencodeOk: true|false`.
+
+This plan was hardened through a full design interview (see **Decision log**). Notably, auth moved
+from Basic-Auth-at-upgrade to an **in-protocol `hello` handshake**, which also prepares a future
+"one account owns many computers, account stored server-side" model without building it yet.
+
+## Decision log (grill outcomes)
+
+| Topic | Decision |
+|---|---|
+| Event shape | Explicit `event` field: `computer_request|computer_response|gateway_request|gateway_response`; `type` = redux action |
+| Bidi scope | All 4 events now; reverse direction (`gateway_request`→`computer_response`) exercised by tests |
+| Duplicate trapos id | **Replace existing (newest-wins)** — deliberate deviation from INIT's "reject the duplicate" |
+| Identity | **Trust the frame** — gateway uses the client-declared `traposId`; no connection↔frame cross-validation |
+| **Auth** | **In-protocol `hello` handshake** — secret in payload; **supersedes** Basic-Auth-at-upgrade + `?id=&label=` query and the "header support" risk |
+| Auth reject | **Terminal**: daemon stops reconnecting on `unauthorized`, stores `lastError`; network drops still reconnect |
+| Error model | `ok` + `error: { code, message }` with a stable code enum |
+| Health disconnected | **Fail fast** with clear error; ~10s command timeout; ~5s opencode probe bound |
+| Opencode wiring | `OPENCODE_SERVER_PASSWORD` + default `OPENCODE_URL=http://127.0.0.1:4242`, Basic Auth (opencode link only) |
+| Health payload | `{ sandboxOk, opencodeOk, opencodeDetail? }` (detail shown only on failure) |
+| Reverse scope (Lua) | Built-in `ping` only; no extensibility fan-out/response path in v1 |
+| Future account seam | `accountId` constant `"local"` via `resolveAccount(secret)`; registry keyed by `(accountId, traposId)`; structured error codes |
+| Host tooling | Full wiring: `just sandbox-serve`, `npm.just`/`install`/`ci`, `docs/public-ports.md` row for 4444 |
+| Meta package | Add `trapos-sandbox` to `trapos` meta + bump version (daemon dormant until `sandbox.url` set) |
+| Versions | Fastify `^5` + `@fastify/websocket` `^11`; `engines.node >=20` (Node 24 in use) |
+| Tests | 3 layers (Lua-unit, TS-unit, TS-integration) + one full-boot e2e |
+
+> The "basic password mechanism" from INIT is preserved *in spirit* (a shared secret =
+> `SANDBOX_PASSWORD`, mirroring `OPENCODE_SERVER_PASSWORD`) but delivered **in-band via the hello
+> frame**, not as a Basic-Auth header. The opencode probe still uses Basic Auth to the opencode
+> server (unchanged).
+
+## Protocol
+
+JSON frames. Computer-originated carry `traposSenderId`; gateway-originated carry `traposReceiverId`.
+`traposId = "<computerId>:<label>"` (label may be empty → `"7:"`).
+
+```
+// computer -> gateway
+{ event:"computer_request",  traposSenderId,   messageId, type, payload }
+{ event:"computer_response", traposSenderId,   messageId, type, ok, payload?, error? }
+// gateway -> computer
+{ event:"gateway_request",   traposReceiverId, messageId, type, payload }
+{ event:"gateway_response",  traposReceiverId, messageId, type, ok, payload?, error? }
+```
+
+- **messageId** is minted by the *initiator*; the reply echoes it. Gateway uses `randomUUID()`;
+  Lua uses `"<os.epoch('utc')>-<_G seq>"` (a process-global monotonic seq so concurrent commands
+  never collide). Each side keys its own pending map by messageId.
+- **Error model**: responses carry `ok:boolean` and, when `ok:false`, `error:{ code, message }`.
+  v1 codes: `unauthorized | not_authenticated | unknown_type | not_connected | internal | timeout`.
+- **Empty-payload gotcha**: CraftOS `textutils.serializeJSON({})` emits `"[]"`. The TS parser treats
+  a missing / array / non-object `payload` as `{}`; the Lua side may omit `payload` when empty and
+  `onMessage` tolerates the same. Covered by a unit test.
+- **Malformed/unknown frames** are ignored (no crash). Each side ignores events it shouldn't receive.
+
+### Handshake (`hello`) — auth + registration + account seam
+1. On socket open, the daemon sends `computer_request type:"hello" payload:{ traposId, secret }`.
+2. Gateway validates `secret` against `SANDBOX_PASSWORD` (unset ⇒ auth disabled, any secret OK),
+   runs `resolveAccount(secret) → "local"`, registers `(accountId, traposId)` (**newest-wins**),
+   stores `{accountId, traposId}` on the socket, and replies
+   `gateway_response type:"hello" ok:true payload:{ accountId }`.
+3. On bad secret → `ok:false error:{code:"unauthorized"}` then close.
+4. Any non-hello frame before a successful hello → `ok:false error:{code:"not_authenticated"}`.
+
+### Concrete types
+- **health** (computer→gateway): `computer_request type:"health"` → `gateway_response type:"health"
+  ok:true payload:{ sandboxOk:true, opencodeOk:boolean, opencodeDetail?:string }`. `sandboxOk` is
+  trivially true; `opencodeOk` from the probe; `opencodeDetail` (url + status/error) only when false.
+- **ping** (gateway→computer, reverse-direction example/test): `gateway_request type:"ping"` →
+  `computer_response type:"ping" ok:true payload:{ traposId }`.
+
+## TypeScript side — `tools/trap-sandbox/`
+
+ESM, `tsc` build, `tsx` dev/test, `node:test`, typescript-eslint flat config (copy mcp-bridge's
+`tsconfig.json`/`eslint.config.js`). Fastify `^5` + `@fastify/websocket` `^11`; `engines.node>=20`.
+
+```
+src/
+├── index.ts        # env config; build app; listen on SANDBOX_PORT; clear EADDRINUSE message + exit
+├── app.ts          # createApp(config): Fastify + GatewayRegistry; register @fastify/websocket + module; returns { app, registry }
+├── auth.ts         # resolveAccount(secret): "local" | null  (constant seam; null = unauthorized)
+├── opencode.ts     # createOpencodeProbe(config): probe(): { ok, detail } via @opencode-ai/sdk
+└── modules/trapos-cloud-gateway/
+    ├── index.ts    # Fastify plugin: GET /health (open) + GET /gateway (ws)
+    ├── protocol.ts # envelope/error types + parse/validate (4 events, hello, empty-payload→{})
+    └── registry.ts # GatewayRegistry keyed by (accountId,traposId); newest-wins; request()+timeout; pending cleanup on close
+test/               # TS unit (protocol, registry, auth/hello, probe) with FakeSocket + fake fetch
+test-integration/   # harness.ts (app on :0, startCraftos, fake-opencode http server) + lua/ + *.test.ts
+```
+
+- **WS `/gateway`** (`{ websocket: true }`): no upgrade auth (auth is the hello frame). `maxPayload`
+  ~1MB. `socket.on("message")` parses a frame inside try/catch → dispatch: pre-hello only `hello` is
+  honored; post-hello handle `computer_request` (`health`, else `unknown_type`) and
+  `computer_response` (resolve pending `gateway_request` by messageId). `close`/`error` → unregister
+  + reject that connection's pendings.
+- **GatewayRegistry**: `register`/`unregister`/`has`/`count`; `request(accountId, traposId, type,
+  payload, timeoutMs=600000)` sends `gateway_request`, races matching `computer_response` vs timeout.
+- **opencode probe**: `createOpencodeClient({ baseUrl: OPENCODE_URL, headers:{ Authorization: basic
+  ("opencode", OPENCODE_SERVER_PASSWORD) }, throwOnError:false })` then `config.get()` with
+  `AbortSignal.timeout(5000)`, wrapped in try/catch. `ok = response 2xx`; `detail` = url + status or
+  error. No `OPENCODE_URL` → `{ ok:false, detail:"OPENCODE_URL not set" }` without a call.
+- **Env** (`index.ts`): `SANDBOX_HOST`(`0.0.0.0`), `SANDBOX_PORT`(`4444`), `SANDBOX_PASSWORD`(unset⇒
+  auth off), `SANDBOX_REQUEST_TIMEOUT_MS`(`600000`), `OPENCODE_URL`(`http://127.0.0.1:4242`),
+  `OPENCODE_SERVER_PASSWORD`, `OPENCODE_USERNAME`(`opencode`).
+- **package.json**: deps `fastify`,`@fastify/websocket`,`@opencode-ai/sdk` (move from devDeps);
+  devDeps copy mcp-bridge (`typescript`,`tsx`,`@eslint/js`,`typescript-eslint`,`@types/node`,
+  `globals`,`eslint`,`@types/ws`); scripts copy mcp-bridge **plus `"lint":"npm run eslint"`**.
+
+## Lua side
+
+### `apis/libsandbox.lua` (new) — template: `apis/libmcpcomputer.lua`
+`createSandbox()` returns:
+- `traposId(osLike)` → `id .. ":" .. (label or "")`.
+- Envelope builders for the 4 events + hello.
+- `onMessage(content, …)`: decode (pcall); `gateway_request`→ built-in `ping` (else
+  `ok:false unknown_type`) replied as `computer_response` via pcall-send; `gateway_response`→ if
+  `type=="hello"` drive the handshake state, else `queueEvent('trapos_sandbox_reply', messageId, ok,
+  payload, error)`.
+- `startSession(opts)` (daemon; injectable `http`/`eventloop`/`encode`/`decode`/`os`): builds the
+  connect URL from base `opts.url`, computes `traposId`; `websocketAsync`; on `websocket_success`
+  send hello; on hello `ok:true` set state=ready + `queueEvent('trapos_sandbox_connected', traposId)`;
+  on hello `ok:false` set state=unauthorized (**terminal**, store `lastError`, close, no reconnect);
+  on `websocket_failure`/`_closed` reconnect via `el.setTimeout(connect, 5)` (unless unauthorized);
+  hello with no ack in ~10s → close + reconnect; `trapos_sandbox_send` handler builds
+  `computer_request`, **pcall-send** only when ready, else fast `trapos_sandbox_reply(messageId,
+  false, nil, {code:"not_connected"})`. Returns `{ isReady, lastError }`.
+- `request(type, payload, opts)` (injectable `queueEvent`/`pullEvent`/`startTimer`): mint messageId,
+  queue `trapos_sandbox_send`, wait for matching `trapos_sandbox_reply` vs a timer (**default 10s**,
+  overridable). Returns `(ok, payloadOrError)`.
+
+**os-event contract** (all `trapos_sandbox_`-prefixed):
+`trapos_sandbox_send(messageId,type,payload)`, `trapos_sandbox_reply(messageId,ok,payload,error)`,
+`trapos_sandbox_connected(traposId)`.
+
+### `servers/sandbox.lua` (new) — template: `servers/mcp-computer-server.lua`
+Read `sandbox.url` (unset/`http.websocket` missing → "daemon inactive", return) and `sandbox.password`;
+`startSession{ eventloop=_G.bootEventLoop, url, password(secret), os }`; print version.
+
+### `programs/sandbox.lua` (new) — template: `programs/ai.lua`
+- Reads `sandbox.url` first; unset → immediate `set sandbox.url first` (no 10s wait).
+- `health` → `request('health')`; print `sandboxOk`/`opencodeOk` (+ `opencode: <detail>` when false);
+  on `not ok` print `sandbox health failed: <code> <message>` (e.g. `unauthorized`, `not_connected`,
+  `timeout`).
+- `--version` / `--help`.
+
+## Package changes
+1. **Rename** `packages/trapos-sandbox/` → `packages/trapos-sandbox-legacy/`; set `"name":
+   "trapos-sandbox-legacy"` (keep its files/autostart).
+2. **New** `packages/trapos-sandbox/ccpm.json`: name `trapos-sandbox`, version `0.1.0`, deps
+   `["trapos-core"]`, files `["apis/libsandbox.lua","programs/sandbox.lua","servers/sandbox.lua"]`,
+   autostart `["servers/sandbox"]`.
+3. **`packages/index.json`**: `trapos-sandbox: "0.1.0"` + add `trapos-sandbox-legacy: "0.2.2"`.
+4. **`packages/trapos/ccpm.json`**: add `trapos-sandbox` to deps; bump meta version.
+
+## Tooling
+- `just/npm.just`: extend recipes (install/build/check/test/test-integration/ci) to cover
+  `tools/trap-sandbox` alongside mcp-bridge; ensure `just install`/`just ci` include it.
+- `just/opencode.just` (or a new recipe): add **`just sandbox-serve`** mirroring `opencode-serve`
+  (source `.env`, export `OPENCODE_SERVER_PASSWORD`, default `OPENCODE_URL`/`SANDBOX_PORT`, run
+  `npm run dev --prefix tools/trap-sandbox`).
+- `docs/public-ports.md`: add a `4444` row (note it sits outside the 4242–4244 range; 4244 reserved).
+
+## Tests
+**Lua unit** (`tests/sandbox.lua`, libtest + fakes): envelope builders, `traposId`, `onMessage`
+dispatch (ping ok / unknown_type / hello), empty-payload coercion, `startSession` wiring (fake
+eventloop+http: hello sent on open, ready on ack, terminal on unauthorized, reconnect on drop),
+`request()` resolve + timeout via injected event primitives.
+
+**TS unit** (`tools/trap-sandbox/test`): protocol parse/validate (4 events, hello, `ok`/`error`,
+empty-payload→`{}`), registry (duplicate newest-wins per account, messageId correlation, timeout,
+pending cleanup on close), `resolveAccount`, opencode probe (fake fetch/server: ok / 401 / timeout).
+
+**TS integration** (`tools/trap-sandbox/test-integration`, real craftos ↔ real gateway, serialized):
+self-contained `gateway-client.lua` for the health round-trip (opencodeOk true/false via the
+fake-opencode server), reverse `ping` via `registry.request`, duplicate (newest-wins), and the
+**auth canary** — wrong secret asserts in-band `hello ok:false code:"unauthorized"`, correct secret
+asserts `hello ok:true`.
+
+**Full-boot e2e** (TS integration): craftos `--exec` replicates boot (set `sandbox.url`,
+`_G.bootEventLoop`, run real `servers/sandbox`, then under `parallel` wait for
+`trapos_sandbox_connected` and run `sandbox health`); assert stdout contains `sandboxOk: true`.
+Bounded by generous timeouts.
+
+## Verification
+- `npm test`, `npm run test:integration`, `npm run lint`/`check` clean in `tools/trap-sandbox`.
+- `just _craftos-test` runs the new `tests/sandbox.lua`; `just ci` covers both tools.
+- Manual: `just sandbox-serve`; in-game `set sandbox.url ws://<host>:4444/gateway` (+
+  `set sandbox.password <secret>` if `SANDBOX_PASSWORD` set), reboot, `sandbox health` →
+  `sandboxOk: true` / `opencodeOk: …`.
+
+## Out of scope / future
+- The account model itself (multi-computer-per-account). Seam only: `resolveAccount`, `(accountId,
+  traposId)` keying, structured errors, hello as the credential→account home.
+- Full opencode integration beyond the health probe; rewriting `ai.lua`; cross-module wiring.
+
+## Known limitations (v1, documented)
+- `traposId = id:label` is **not unique across Minecraft servers/worlds** (computer ids reset per
+  world; labels may be empty). With newest-wins, a cross-server collision would evict the other
+  computer. Accepted per INIT ("id+label for now"); the future account model is the real fix.
+- No rate-limiting / per-frame size policing beyond `maxPayload`; no reconnect backoff (fixed 5s);
+  trusted-LAN assumptions.
diff --git a/.plans/trap-sandbox/01-ts-gateway.md b/.plans/trap-sandbox/01-ts-gateway.md
new file mode 100644
index 0000000..3e26f73
--- /dev/null
+++ b/.plans/trap-sandbox/01-ts-gateway.md
@@ -0,0 +1,75 @@
+# 01 — TS gateway (`tools/trap-sandbox/`)
+
+> Sub-plan of [trap-sandbox-gateway-spec](./trap-sandbox-gateway-spec.md). Implements the
+> **Protocol** and **Handshake** contracts defined there — do not redefine frame shapes or error
+> codes here; reference the spec. **Build first** (M1): no Lua dependency.
+
+## Scope
+The TypeScript service: Fastify app on port 4444, the `trapos-cloud-gateway` module
+(protocol/registry/WS), the opencode probe, the auth seam, env/config, package wiring, and TS
+**unit** tests. Integration/e2e tests live in [04-integration-tooling](./04-integration-tooling.md).
+
+## Task checklist
+- [ ] Scaffold `tools/trap-sandbox/` (ESM, `tsc` build, `tsx` dev/test, `node:test`, typescript-eslint
+      flat config — copy `mcp-bridge`'s `tsconfig.json`/`eslint.config.js`).
+- [ ] `package.json`: deps + devDeps + scripts (see below).
+- [ ] `src/auth.ts` — `resolveAccount(secret)`.
+- [ ] `src/opencode.ts` — `createOpencodeProbe(config)`.
+- [ ] `src/modules/trapos-cloud-gateway/protocol.ts` — envelope/error types + parse/validate.
+- [ ] `src/modules/trapos-cloud-gateway/registry.ts` — `GatewayRegistry`.
+- [ ] `src/modules/trapos-cloud-gateway/index.ts` — Fastify plugin: `GET /health` (open) + `GET /gateway` (ws).
+- [ ] `src/app.ts` — `createApp(config)` returning `{ app, registry }`.
+- [ ] `src/index.ts` — env config, listen, `EADDRINUSE` clear message + exit.
+- [ ] TS unit tests (`test/`): protocol, registry, auth/hello, probe.
+- [ ] Gate: `npm test`, `npm run lint`/`check` clean.
+
+## Layout
+ESM, `tsc` build, `tsx` dev/test, `node:test`, typescript-eslint flat config (copy mcp-bridge's
+`tsconfig.json`/`eslint.config.js`). Fastify `^5` + `@fastify/websocket` `^11`; `engines.node>=20`.
+
+```
+src/
+├── index.ts        # env config; build app; listen on SANDBOX_PORT; clear EADDRINUSE message + exit
+├── app.ts          # createApp(config): Fastify + GatewayRegistry; register @fastify/websocket + module; returns { app, registry }
+├── auth.ts         # resolveAccount(secret): "local" | null  (constant seam; null = unauthorized)
+├── opencode.ts     # createOpencodeProbe(config): probe(): { ok, detail } via @opencode-ai/sdk
+└── modules/trapos-cloud-gateway/
+    ├── index.ts    # Fastify plugin: GET /health (open) + GET /gateway (ws)
+    ├── protocol.ts # envelope/error types + parse/validate (4 events, hello, empty-payload→{})
+    └── registry.ts # GatewayRegistry keyed by (accountId,traposId); newest-wins; request()+timeout; pending cleanup on close
+test/               # TS unit (protocol, registry, auth/hello, probe) with FakeSocket + fake fetch
+```
+
+## Behavior
+- **WS `/gateway`** (`{ websocket: true }`): no upgrade auth (auth is the hello frame). `maxPayload`
+  ~1MB. `socket.on("message")` parses a frame inside try/catch → dispatch: pre-hello only `hello` is
+  honored; post-hello handle `computer_request` (`health`, else `unknown_type`) and
+  `computer_response` (resolve pending `gateway_request` by messageId). `close`/`error` → unregister
+  + reject that connection's pendings. (Handshake steps & error codes: see spec **Handshake**.)
+- **GatewayRegistry**: `register`/`unregister`/`has`/`count`; `request(accountId, traposId, type,
+  payload, timeoutMs=600000)` sends `gateway_request`, races matching `computer_response` vs timeout.
+  Keyed by `(accountId, traposId)`, newest-wins.
+- **opencode probe**: `createOpencodeClient({ baseUrl: OPENCODE_URL, headers:{ Authorization: basic
+  ("opencode", OPENCODE_SERVER_PASSWORD) }, throwOnError:false })` then `config.get()` with
+  `AbortSignal.timeout(5000)`, wrapped in try/catch. `ok = response 2xx`; `detail` = url + status or
+  error. No `OPENCODE_URL` → `{ ok:false, detail:"OPENCODE_URL not set" }` without a call.
+- **auth**: `resolveAccount(secret)` → `"local" | null` (constant seam; `null` = unauthorized).
+
+## Env (`index.ts`)
+`SANDBOX_HOST`(`0.0.0.0`), `SANDBOX_PORT`(`4444`), `SANDBOX_PASSWORD`(unset⇒ auth off),
+`SANDBOX_REQUEST_TIMEOUT_MS`(`600000`), `OPENCODE_URL`(`http://127.0.0.1:4242`),
+`OPENCODE_SERVER_PASSWORD`, `OPENCODE_USERNAME`(`opencode`).
+
+## package.json
+- deps: `fastify`, `@fastify/websocket`, `@opencode-ai/sdk` (move from devDeps).
+- devDeps: copy mcp-bridge (`typescript`, `tsx`, `@eslint/js`, `typescript-eslint`, `@types/node`,
+  `globals`, `eslint`, `@types/ws`).
+- scripts: copy mcp-bridge **plus `"lint":"npm run eslint"`**.
+
+## TS unit tests (`test/`)
+Protocol parse/validate (4 events, hello, `ok`/`error`, empty-payload→`{}`), registry (duplicate
+newest-wins per account, messageId correlation, timeout, pending cleanup on close), `resolveAccount`,
+opencode probe (fake fetch/server: ok / 401 / timeout). Use `FakeSocket` + fake fetch.
+
+## Verification gate
+`npm test` + `npm run lint`/`check` clean in `tools/trap-sandbox`; service starts and listens on 4444.
diff --git a/.plans/trap-sandbox/02-lua-client.md b/.plans/trap-sandbox/02-lua-client.md
new file mode 100644
index 0000000..84c1a2d
--- /dev/null
+++ b/.plans/trap-sandbox/02-lua-client.md
@@ -0,0 +1,56 @@
+# 02 — Lua client (`trapos-sandbox`)
+
+> Sub-plan of [trap-sandbox-gateway-spec](./trap-sandbox-gateway-spec.md). Implements the
+> **Protocol**, **Handshake**, and **os-event contract** from the spec — reference them, don't
+> redefine. M2; depends on the protocol contract (not on M1 code existing).
+
+## Scope
+The Lua side: `apis/libsandbox.lua`, `servers/sandbox.lua`, `programs/sandbox.lua`, and Lua **unit**
+tests. Package/meta changes are [03-packages](./03-packages.md); integration/e2e is
+[04-integration-tooling](./04-integration-tooling.md).
+
+## Task checklist
+- [ ] `apis/libsandbox.lua` (template: `apis/libmcpcomputer.lua`).
+- [ ] `servers/sandbox.lua` (template: `servers/mcp-computer-server.lua`).
+- [ ] `programs/sandbox.lua` (template: `programs/ai.lua`).
+- [ ] Lua unit tests (`tests/sandbox.lua`).
+- [ ] Gate: `just _craftos-test` runs `tests/sandbox.lua` green.
+
+## `apis/libsandbox.lua` — template: `apis/libmcpcomputer.lua`
+`createSandbox()` returns:
+- `traposId(osLike)` → `id .. ":" .. (label or "")`.
+- Envelope builders for the 4 events + hello.
+- `onMessage(content, …)`: decode (pcall); `gateway_request`→ built-in `ping` (else
+  `ok:false unknown_type`) replied as `computer_response` via pcall-send; `gateway_response`→ if
+  `type=="hello"` drive the handshake state, else `queueEvent('trapos_sandbox_reply', messageId, ok,
+  payload, error)`.
+- `startSession(opts)` (daemon; injectable `http`/`eventloop`/`encode`/`decode`/`os`): builds the
+  connect URL from base `opts.url`, computes `traposId`; `websocketAsync`; on `websocket_success`
+  send hello; on hello `ok:true` set state=ready + `queueEvent('trapos_sandbox_connected', traposId)`;
+  on hello `ok:false` set state=unauthorized (**terminal**, store `lastError`, close, no reconnect);
+  on `websocket_failure`/`_closed` reconnect via `el.setTimeout(connect, 5)` (unless unauthorized);
+  hello with no ack in ~10s → close + reconnect; `trapos_sandbox_send` handler builds
+  `computer_request`, **pcall-send** only when ready, else fast `trapos_sandbox_reply(messageId,
+  false, nil, {code:"not_connected"})`. Returns `{ isReady, lastError }`.
+- `request(type, payload, opts)` (injectable `queueEvent`/`pullEvent`/`startTimer`): mint messageId,
+  queue `trapos_sandbox_send`, wait for matching `trapos_sandbox_reply` vs a timer (**default 10s**,
+  overridable). Returns `(ok, payloadOrError)`.
+
+## `servers/sandbox.lua` — template: `servers/mcp-computer-server.lua`
+Read `sandbox.url` (unset/`http.websocket` missing → "daemon inactive", return) and `sandbox.password`;
+`startSession{ eventloop=_G.bootEventLoop, url, password(secret), os }`; print version.
+
+## `programs/sandbox.lua` — template: `programs/ai.lua`
+- Reads `sandbox.url` first; unset → immediate `set sandbox.url first` (no 10s wait).
+- `health` → `request('health')`; print `sandboxOk`/`opencodeOk` (+ `opencode: <detail>` when false);
+  on `not ok` print `sandbox health failed: <code> <message>` (e.g. `unauthorized`, `not_connected`,
+  `timeout`).
+- `--version` / `--help`.
+
+## Lua unit tests (`tests/sandbox.lua`, libtest + fakes)
+Envelope builders, `traposId`, `onMessage` dispatch (ping ok / unknown_type / hello), empty-payload
+coercion, `startSession` wiring (fake eventloop+http: hello sent on open, ready on ack, terminal on
+unauthorized, reconnect on drop), `request()` resolve + timeout via injected event primitives.
+
+## Verification gate
+`just _craftos-test` runs the new `tests/sandbox.lua` green.
diff --git a/.plans/trap-sandbox/03-packages.md b/.plans/trap-sandbox/03-packages.md
new file mode 100644
index 0000000..b2125d1
--- /dev/null
+++ b/.plans/trap-sandbox/03-packages.md
@@ -0,0 +1,27 @@
+# 03 — Packages (rename + new package + meta)
+
+> Sub-plan of [trap-sandbox-gateway-spec](./trap-sandbox-gateway-spec.md). Mechanical wiring. M3;
+> may run in parallel with M2. Depends on the Lua file paths from
+> [02-lua-client](./02-lua-client.md) being settled.
+
+## Scope
+ccpm package definitions only: rename the legacy package, register the new `trapos-sandbox`, keep
+`packages/index.json` consistent, and add `trapos-sandbox` to the `trapos` meta with a version bump.
+
+## Task checklist
+- [ ] **Rename** `packages/trapos-sandbox/` → `packages/trapos-sandbox-legacy/`; set
+      `"name": "trapos-sandbox-legacy"` (keep its files/autostart).
+- [ ] **New** `packages/trapos-sandbox/ccpm.json`: name `trapos-sandbox`, version `0.1.0`, deps
+      `["trapos-core"]`, files `["apis/libsandbox.lua","programs/sandbox.lua","servers/sandbox.lua"]`,
+      autostart `["servers/sandbox"]`.
+- [ ] **`packages/index.json`**: `trapos-sandbox: "0.1.0"` + add `trapos-sandbox-legacy: "0.2.2"`.
+- [ ] **`packages/trapos/ccpm.json`**: add `trapos-sandbox` to deps; bump meta version.
+
+## Notes
+- The daemon stays dormant until `sandbox.url` is set, so adding it to the `trapos` meta is safe.
+- Confirm the legacy version pinned in `index.json` (`0.2.2`) matches the renamed package's current
+  version before committing.
+
+## Verification gate
+`packages/index.json` resolves both names; `trapos` meta installs `trapos-sandbox`; legacy package
+still installs under its new name with files/autostart intact.
diff --git a/.plans/trap-sandbox/04-integration-tooling.md b/.plans/trap-sandbox/04-integration-tooling.md
new file mode 100644
index 0000000..e1bca04
--- /dev/null
+++ b/.plans/trap-sandbox/04-integration-tooling.md
@@ -0,0 +1,49 @@
+# 04 — Integration & tooling
+
+> Sub-plan of [trap-sandbox-gateway-spec](./trap-sandbox-gateway-spec.md). **Build last** (M4):
+> requires both the TS gateway (M1) and the Lua client (M2) to exist. References the spec's
+> **Protocol**/**Handshake** for assertions.
+
+## Scope
+Host tooling (`just`/`npm.just` recipes, `sandbox-serve`, docs) and the cross-side tests: TS
+**integration** (real craftos ↔ real gateway) plus the **full-boot e2e**.
+
+## Task checklist
+- [ ] `just/npm.just`: extend `install/build/check/test/test-integration/ci` to cover
+      `tools/trap-sandbox` alongside mcp-bridge; ensure `just install`/`just ci` include it.
+- [ ] `just/opencode.just` (or new recipe): add **`just sandbox-serve`** mirroring `opencode-serve`.
+- [ ] `docs/public-ports.md`: add a `4444` row.
+- [ ] TS integration harness + cases (`tools/trap-sandbox/test-integration/`).
+- [ ] Full-boot e2e.
+- [ ] Gate: `npm run test:integration` green; `just ci` covers both tools.
+
+## Tooling
+- `just/npm.just`: extend recipes (install/build/check/test/test-integration/ci) to cover
+  `tools/trap-sandbox` alongside mcp-bridge; ensure `just install`/`just ci` include it.
+- `just/opencode.just` (or a new recipe): add **`just sandbox-serve`** mirroring `opencode-serve`
+  (source `.env`, export `OPENCODE_SERVER_PASSWORD`, default `OPENCODE_URL`/`SANDBOX_PORT`, run
+  `npm run dev --prefix tools/trap-sandbox`).
+- `docs/public-ports.md`: add a `4444` row (note it sits outside the 4242–4244 range; 4244 reserved).
+
+## Test layout
+```
+test-integration/   # harness.ts (app on :0, startCraftos, fake-opencode http server) + lua/ + *.test.ts
+```
+
+## TS integration (`tools/trap-sandbox/test-integration`, real craftos ↔ real gateway, serialized)
+Self-contained `gateway-client.lua` for the health round-trip (opencodeOk true/false via the
+fake-opencode server), reverse `ping` via `registry.request`, duplicate (newest-wins), and the
+**auth canary** — wrong secret asserts in-band `hello ok:false code:"unauthorized"`, correct secret
+asserts `hello ok:true`.
+
+## Full-boot e2e (TS integration)
+craftos `--exec` replicates boot (set `sandbox.url`, `_G.bootEventLoop`, run real `servers/sandbox`,
+then under `parallel` wait for `trapos_sandbox_connected` and run `sandbox health`); assert stdout
+contains `sandboxOk: true`. Bounded by generous timeouts.
+
+## Verification gate (also the project-level acceptance)
+- `npm test`, `npm run test:integration`, `npm run lint`/`check` clean in `tools/trap-sandbox`.
+- `just _craftos-test` runs `tests/sandbox.lua`; `just ci` covers both tools.
+- Manual: `just sandbox-serve`; in-game `set sandbox.url ws://<host>:4444/gateway` (+
+  `set sandbox.password <secret>` if `SANDBOX_PASSWORD` set), reboot, `sandbox health` →
+  `sandboxOk: true` / `opencodeOk: …`.
diff --git a/.plans/trap-sandbox/trap-sandbox-gateway-spec.md b/.plans/trap-sandbox/trap-sandbox-gateway-spec.md
new file mode 100644
index 0000000..8ccbbc8
--- /dev/null
+++ b/.plans/trap-sandbox/trap-sandbox-gateway-spec.md
@@ -0,0 +1,136 @@
+# Spec: trap-sandbox gateway + trapos-sandbox client (first iteration)
+
+> **Status: SETTLED — do not revisit the Decision log.** The decisions below were hardened
+> through a full design interview and are frozen input for every sub-plan. If a sub-plan
+> surfaces a reason to reopen one, stop and raise it here first; do not silently deviate.
+
+This is the **shared contract**. Sub-plans implement against it. The cross-cutting pieces
+(Context, Decision log, Protocol, Out-of-scope, Known limitations) live here and are *not*
+duplicated into sub-plans — sub-plans link back to this file.
+
+## Context
+
+`tools/trap-sandbox/` is a new TypeScript service that replaces the legacy `tools/mcp-bridge`
+(kept only for inspiration). It delivers a **general-purpose Fastify API on port 4444**, organized
+into "sandbox modules" (Fastify plugins). The only module in this iteration is the
+**`trapos-cloud-gateway`**: a WebSocket gateway giving a CraftOS (trapos) computer and the
+sandbox/opencode a generic, bi-directional request/reply protocol.
+
+On the Lua side, a new `trapos-sandbox` package installs `servers/sandbox.lua` (a boot daemon that
+owns one persistent WS connection and bridges WS frames to in-OS events) plus a `sandbox` command.
+The legacy `trapos-sandbox` package is renamed to `trapos-sandbox-legacy`.
+
+**Intended outcome:** after installing the new trapos and setting `sandbox.url`, running
+`sandbox health` in-game prints `sandboxOk: true` / `opencodeOk: true|false`.
+
+This plan was hardened through a full design interview (see **Decision log**). Notably, auth moved
+from Basic-Auth-at-upgrade to an **in-protocol `hello` handshake**, which also prepares a future
+"one account owns many computers, account stored server-side" model without building it yet.
+
+## Milestones & todolist
+
+High-level only — each sub-plan owns its granular steps. Tick a milestone when its sub-plan's
+verification gate is green.
+
+- [ ] **M1 — TS gateway** ([01-ts-gateway](./01-ts-gateway.md)): service builds, listens on 4444,
+  TS unit tests green (`npm test`, `npm run lint`/`check` clean). *No Lua dependency — build first.*
+- [ ] **M2 — Lua client** ([02-lua-client](./02-lua-client.md)): `libsandbox`/`servers`/`programs`
+  in place, Lua unit tests green via `just _craftos-test`. *Implements the Protocol contract.*
+- [ ] **M3 — Packages** ([03-packages](./03-packages.md)): legacy renamed, new `trapos-sandbox`
+  package + meta bump wired; `packages/index.json` consistent.
+- [ ] **M4 — Integration & tooling** ([04-integration-tooling](./04-integration-tooling.md)):
+  `just` recipes, `docs/public-ports.md`, TS integration harness + full-boot e2e green.
+  *Requires both sides — build last.*
+
+Dependency order: **M1 → M2 → M3 → M4**. M3 may proceed in parallel with M2 (mechanical).
+
+## Sub-plans index
+
+| # | Sub-plan | Scope |
+|---|---|---|
+| 01 | [TS gateway](./01-ts-gateway.md) | `tools/trap-sandbox/` service, registry, protocol, opencode probe, TS unit tests |
+| 02 | [Lua client](./02-lua-client.md) | `apis/libsandbox.lua`, `servers/sandbox.lua`, `programs/sandbox.lua`, Lua unit tests |
+| 03 | [Packages](./03-packages.md) | legacy rename, new package, `index.json`, meta bump |
+| 04 | [Integration & tooling](./04-integration-tooling.md) | `just`/`npm.just`, `sandbox-serve`, docs, TS integration + full-boot e2e |
+
+## Decision log (grill outcomes)
+
+| Topic | Decision |
+|---|---|
+| Event shape | Explicit `event` field: `computer_request|computer_response|gateway_request|gateway_response`; `type` = redux action |
+| Bidi scope | All 4 events now; reverse direction (`gateway_request`→`computer_response`) exercised by tests |
+| Duplicate trapos id | **Replace existing (newest-wins)** — deliberate deviation from INIT's "reject the duplicate" |
+| Identity | **Trust the frame** — gateway uses the client-declared `traposId`; no connection↔frame cross-validation |
+| **Auth** | **In-protocol `hello` handshake** — secret in payload; **supersedes** Basic-Auth-at-upgrade + `?id=&label=` query and the "header support" risk |
+| Auth reject | **Terminal**: daemon stops reconnecting on `unauthorized`, stores `lastError`; network drops still reconnect |
+| Error model | `ok` + `error: { code, message }` with a stable code enum |
+| Health disconnected | **Fail fast** with clear error; ~10s command timeout; ~5s opencode probe bound |
+| Opencode wiring | `OPENCODE_SERVER_PASSWORD` + default `OPENCODE_URL=http://127.0.0.1:4242`, Basic Auth (opencode link only) |
+| Health payload | `{ sandboxOk, opencodeOk, opencodeDetail? }` (detail shown only on failure) |
+| Reverse scope (Lua) | Built-in `ping` only; no extensibility fan-out/response path in v1 |
+| Future account seam | `accountId` constant `"local"` via `resolveAccount(secret)`; registry keyed by `(accountId, traposId)`; structured error codes |
+| Host tooling | Full wiring: `just sandbox-serve`, `npm.just`/`install`/`ci`, `docs/public-ports.md` row for 4444 |
+| Meta package | Add `trapos-sandbox` to `trapos` meta + bump version (daemon dormant until `sandbox.url` set) |
+| Versions | Fastify `^5` + `@fastify/websocket` `^11`; `engines.node >=20` (Node 24 in use) |
+| Tests | 3 layers (Lua-unit, TS-unit, TS-integration) + one full-boot e2e |
+
+> The "basic password mechanism" from INIT is preserved *in spirit* (a shared secret =
+> `SANDBOX_PASSWORD`, mirroring `OPENCODE_SERVER_PASSWORD`) but delivered **in-band via the hello
+> frame**, not as a Basic-Auth header. The opencode probe still uses Basic Auth to the opencode
+> server (unchanged).
+
+## Protocol
+
+JSON frames. Computer-originated carry `traposSenderId`; gateway-originated carry `traposReceiverId`.
+`traposId = "<computerId>:<label>"` (label may be empty → `"7:"`).
+
+```
+// computer -> gateway
+{ event:"computer_request",  traposSenderId,   messageId, type, payload }
+{ event:"computer_response", traposSenderId,   messageId, type, ok, payload?, error? }
+// gateway -> computer
+{ event:"gateway_request",   traposReceiverId, messageId, type, payload }
+{ event:"gateway_response",  traposReceiverId, messageId, type, ok, payload?, error? }
+```
+
+- **messageId** is minted by the *initiator*; the reply echoes it. Gateway uses `randomUUID()`;
+  Lua uses `"<os.epoch('utc')>-<_G seq>"` (a process-global monotonic seq so concurrent commands
+  never collide). Each side keys its own pending map by messageId.
+- **Error model**: responses carry `ok:boolean` and, when `ok:false`, `error:{ code, message }`.
+  v1 codes: `unauthorized | not_authenticated | unknown_type | not_connected | internal | timeout`.
+- **Empty-payload gotcha**: CraftOS `textutils.serializeJSON({})` emits `"[]"`. The TS parser treats
+  a missing / array / non-object `payload` as `{}`; the Lua side may omit `payload` when empty and
+  `onMessage` tolerates the same. Covered by a unit test.
+- **Malformed/unknown frames** are ignored (no crash). Each side ignores events it shouldn't receive.
+
+### Handshake (`hello`) — auth + registration + account seam
+1. On socket open, the daemon sends `computer_request type:"hello" payload:{ traposId, secret }`.
+2. Gateway validates `secret` against `SANDBOX_PASSWORD` (unset ⇒ auth disabled, any secret OK),
+   runs `resolveAccount(secret) → "local"`, registers `(accountId, traposId)` (**newest-wins**),
+   stores `{accountId, traposId}` on the socket, and replies
+   `gateway_response type:"hello" ok:true payload:{ accountId }`.
+3. On bad secret → `ok:false error:{code:"unauthorized"}` then close.
+4. Any non-hello frame before a successful hello → `ok:false error:{code:"not_authenticated"}`.
+
+### Concrete types
+- **health** (computer→gateway): `computer_request type:"health"` → `gateway_response type:"health"
+  ok:true payload:{ sandboxOk:true, opencodeOk:boolean, opencodeDetail?:string }`. `sandboxOk` is
+  trivially true; `opencodeOk` from the probe; `opencodeDetail` (url + status/error) only when false.
+- **ping** (gateway→computer, reverse-direction example/test): `gateway_request type:"ping"` →
+  `computer_response type:"ping" ok:true payload:{ traposId }`.
+
+### os-event contract (Lua, all `trapos_sandbox_`-prefixed)
+`trapos_sandbox_send(messageId,type,payload)`, `trapos_sandbox_reply(messageId,ok,payload,error)`,
+`trapos_sandbox_connected(traposId)`.
+
+## Out of scope / future
+- The account model itself (multi-computer-per-account). Seam only: `resolveAccount`, `(accountId,
+  traposId)` keying, structured errors, hello as the credential→account home.
+- Full opencode integration beyond the health probe; rewriting `ai.lua`; cross-module wiring.
+
+## Known limitations (v1, documented)
+- `traposId = id:label` is **not unique across Minecraft servers/worlds** (computer ids reset per
+  world; labels may be empty). With newest-wins, a cross-server collision would evict the other
+  computer. Accepted per INIT ("id+label for now"); the future account model is the real fix.
+- No rate-limiting / per-frame size policing beyond `maxPayload`; no reconnect backoff (fixed 5s);
+  trusted-LAN assumptions.