appserver kiss backend: argv contract drift — the dispatcher calls `send --socket … --thread …` (stdin line), the transport implements `send <thread> "<line>" --json`; the backend has never delivered live #135

New issue

Open

opened 2026-10-28 15:25:00 +00:00 by claude · 0 comments

claude agent commented

2026-10-28 15:25:00 +00:00

Member

Contract drift between the `appserver` kiss backend and the transport it calls (found 2026-10-28 during the owner's "check skill + contract" round)

Dispatcher (v1.0.94/v1.0.95, kiss_appserver.py:148-155): requires a socket path that exists on disk (socket-missing otherwise) and spawns

<bin> send --socket <socket> --thread <thread>      # line on STDIN, no --json

Transport (oo-appserver v0.5.1, libexec/appserver_send.py:741-754, README "Backend contract"):

oo-appserver send <thread> "<line>" --json [--from NAME] [--wait S] [--min-interval 0]

positional thread and line, no --socket, no --thread, no stdin line; the receipt comes only with --json. The shared server listens on ws://127.0.0.1:8937 — there is no control socket on disk any more (the ~/.codex/app-server-control/app-server-control.sock of the config example does not exist), so a correctly configured target already dies at the pre-spawn check, and with any existing path the spawn dies at argparse (unrecognized arguments: --socket … --thread …, exit 2) → the backend maps it to refused exit-2. Consequence: the appserver backend has never delivered live; today's fleet kisses to Mama/Luna still ride the codex backend (codex exec resume), which the app's held threads refuse as thread-held — exactly the gap the appserver backend was built to close (the owner's wake-up round for Mama needs it).

Suggested fix (one contract, two repos — the README contract is the implemented one):

kiss_appserver.py: argv [bin, "send", thread, line, "--json", "--from", "oo-dispatch", "--min-interval", "0", "--wait", str(timeout_s)] (line as an argument — it is a milestone, not a secret; or keep stdin only if oo-appserver grows a --stdin flag), drop the socket field/check (replace the liveness pre-check with GET http://127.0.0.1:8937/readyz or skip — send names door-closed/held-by-app itself), map the transport's class as documented (delivered-headless/delivered-app-start → delivered, delivered-app-steer → steered, held-by-app, heal-skipped, door-closed, loading, ack-unknown, refused, timeout).
Config shape in USAGE §34.2 / README row: bin + thread (no socket); the suite's fake transport must mirror the real argv (it currently proves the wrong contract).
Alternative if Z prefers the stdin form: oo-appserver can add --thread and --stdin parity flags (the Claude house would ship that in v0.5.2) — but --socket has no meaning for a TCP server and should go either way.

Evidence: both sources quoted above; oo-appserver send --help on the station; ~/.zcode/tmp/claude-adapter-design-20261027/NACHTWACHE.md 2026-10-28 16:2x. Related: #134 (claude-session accepted ≠ delivered), release v1.0.95, oo-appserver README "Backend contract (for appserver in oo-dispatch)".

🤖 Generated with Claude Code

## Contract drift between the `appserver` kiss backend and the transport it calls (found 2026-10-28 during the owner's "check skill + contract" round) **Dispatcher (v1.0.94/v1.0.95, `kiss_appserver.py:148-155`):** requires a `socket` path that exists on disk (`socket-missing` otherwise) and spawns ``` <bin> send --socket <socket> --thread <thread> # line on STDIN, no --json ``` **Transport (oo-appserver v0.5.1, `libexec/appserver_send.py:741-754`, README "Backend contract"):** ``` oo-appserver send <thread> "<line>" --json [--from NAME] [--wait S] [--min-interval 0] ``` positional `thread` and `line`, no `--socket`, no `--thread`, no stdin line; the receipt comes only with `--json`. The shared server listens on `ws://127.0.0.1:8937` — there is no control socket on disk any more (the `~/.codex/app-server-control/app-server-control.sock` of the config example does not exist), so a correctly configured target already dies at the pre-spawn check, and with any existing path the spawn dies at argparse (`unrecognized arguments: --socket … --thread …`, exit 2) → the backend maps it to `refused exit-2`. **Consequence:** the `appserver` backend has never delivered live; today's fleet kisses to Mama/Luna still ride the `codex` backend (`codex exec resume`), which the app's held threads refuse as `thread-held` — exactly the gap the appserver backend was built to close (the owner's wake-up round for Mama needs it). **Suggested fix (one contract, two repos — the README contract is the implemented one):** - `kiss_appserver.py`: argv `[bin, "send", thread, line, "--json", "--from", "oo-dispatch", "--min-interval", "0", "--wait", str(timeout_s)]` (line as an argument — it is a milestone, not a secret; or keep stdin only if oo-appserver grows a `--stdin` flag), drop the `socket` field/check (replace the liveness pre-check with `GET http://127.0.0.1:8937/readyz` or skip — `send` names `door-closed`/`held-by-app` itself), map the transport's `class` as documented (`delivered-headless`/`delivered-app-start` → delivered, `delivered-app-steer` → steered, `held-by-app`, `heal-skipped`, `door-closed`, `loading`, `ack-unknown`, `refused`, `timeout`). - Config shape in USAGE §34.2 / README row: `bin` + `thread` (no `socket`); the suite's fake transport must mirror the real argv (it currently proves the wrong contract). - Alternative if Z prefers the stdin form: oo-appserver can add `--thread` and `--stdin` parity flags (the Claude house would ship that in v0.5.2) — but `--socket` has no meaning for a TCP server and should go either way. Evidence: both sources quoted above; `oo-appserver send --help` on the station; `~/.zcode/tmp/claude-adapter-design-20261027/NACHTWACHE.md` 2026-10-28 16:2x. Related: #134 (claude-session accepted ≠ delivered), release v1.0.95, oo-appserver README "Backend contract (for `appserver` in oo-dispatch)". 🤖 Generated with [Claude Code](https://claude.com/claude-code)