feat(desktop): codex app-server driver, and the input shapes codex rejects (L4c)

[physercoe]

Vision-parity L4c — the codex driver. L4a chose the rung, L4b opened the byte path, and neither was imported by main.ts. This is what makes the lane user-visible: pick codex in the Companion's local picker and the dock drives a real app-server thread.

Continues #568 (L4a) and #569 (L4b). Plan: docs/plans/desktop-companion-vision-parity.md, lane L.

What ships

• localagent/codexwire.ts — pure JSON-RPC shapes: thread params, turn input, server-request classification, per-method response shapes.
• localagent/codexdriver.ts — the session: handshake, queued input, turn/interrupt, delta throttling, parked approvals, resume.
• localagent/driver.ts — the engine-neutral vocabulary (posture, input kinds, DriverEvent, LocalDriver), moved out of claudewire.ts. With two engines, a type named after claude that codex has to import is a name that lies to the next reader.
• service.ts picks a driver per family and routes rebind by resume mechanism.

Notifications go through the L2 interpreter with the hub's own codex frame profile, already shipped in agent_families.generated.json — so a local codex transcript and a hub-driven one are the same rows. No second vocabulary.

★★ Two of the shapes we ship are rejected by codex

Measured against a live codex-cli 0.147.0:

sent	answer
{type:"input_image", image_url:"data:…"}	-32600 Invalid request: unknown variant 'input_image', expected one of 'text', 'image', 'localImage', 'audio', 'localAudio', 'skill', 'mention'
{type:"input_file", file_data:"data:…"}	the same error
{type:"image", url:"data:…"}	accepted — the model described the pixel

Those are OpenAI responses-API content types, not app-server ones. This is not only the new driver's problem: the hub's AppServerDriver.startTurn has sent both since W4.3, so E4's image passthrough has never reached a codex M2 agent, and a PDF was worse than a no-op — an unknown variant fails the whole turn/start, taking the director's message with it. Fixed here, with the strip-and-warn shape driver_exec_resume.go already uses for what gemini cannot carry.

The registry asserted it too: codex.prompt_pdf.M2 was true (what the F3 composer gate reads) and is now false — 0.147.0's UserInput union has no file variant at all. prompt_image.M2 stays true; only the shape was wrong.

Why a green suite missed it: the Go test's fake app-server accepts any params, so it pinned the shipped shape rather than the protocol — a fixture that cannot disprove the rule it tests. Hence an opt-in live e2e.

The plan line that was wrong

"resume argv from the N1 table" names a rung this driver does not use — and N1's own table says so: the codex family row reads mechanism: appserver_thread_resume, with a note that the codex resume <id> CLI recipe is a different rung. service.rebind now routes by mechanism: argv families get a splice, the rest hand their handle to a driver that knows what to do with it.

Other measurements the driver is built on

• thread/resume restores memory and emits no replay — the only notifications after it are configWarning, remoteControl/status/changed, thread/status/changed, thread/tokenUsage/updated, thread/goal/cleared. Same shape as claude's --resume, so L3b's durable log restores the view here too. (Its response does carry thread.turns[], unlike claude's — recorded, not used.)
• sandbox: read-only + approvalPolicy: never is a real write barrier. Asked to create a file in its cwd, codex tried, failed, said "the environment is read-only", and nothing appeared on disk. The response echoes {"type":"readOnly","networkAccess":false}. converse cannot be kept exactly (codex has no tool-disable switch), so the lifecycle row carries a posture_note rather than implying a boundary that is not there.

Approvals, with no attention table

Server requests become approval_request events in R1's own shapes, answered by the cards that already ship — which is exactly what R1's comment predicted. Four kinds are refused at once rather than parked, because a card nobody can answer holds the engine open forever: a form-mode elicitation, a url elicitation, item/permissions/requestApproval (its response is a granted profile, not a verdict), and — the one worth naming — a question codex marks isSecret, since service.input() records every input into the durable on-disk transcript before sending it. Each refusal uses that method's own response shape; an empty {} fails to deserialize on every one of them.

Config seeding rides thread/start.config, so configuring a session never leaves a .codex/config.toml in the director's project.

Verification

• 716 electron tests, 0 fail, 6 skipped (the two live e2e skip without their env var). 49 new.
• go build ./..., go vet ./..., go test ./... — all clean.
• CI's full lint set clean, including lint-openapi.sh and lint-desktop-tokens.sh.
• Live e2e passes against a real codex app-server (TERMIPOD_CODEX_DRIVER_E2E=1): a real turn round-trips with streamed partials, thread/resume finds the thread and the engine remembers, and an image reaches the model.

The e2e earned itself on its first run by failing two of my assertions: one asserted a streamed partial on a reply too short to produce one (a race), and the other asserted the wrong colour — the widely-copied 1×1 "red dot" PNG is RGBA(255,0,0,127), and a half-transparent pixel gets described differently depending on what it is composited against. It now uses an opaque pure-green pixel, since red and blue are what a model guesses when it cannot see the image at all.

Left in the lane, named rather than skipped

No posture maps to approvalPolicy: on-request, so codex's own command/file-change gates never fire from a Companion session today. Adding one is a posture decision, not a driver change — the approval path is built and tested, and MCP elicitations already exercise it.

🤖 Generated with Claude Code