test(control-api): make the cross-product contract a gate

[yeroo]

Task 6 of the product split. agliteterm ships from its own repository promising to speak the agwintermctl dialect. This is the canonical statement of what that means — 38 verbs, each with its request and expected response shape, driven through the real agwintermctl against a sandbox instance.

agliteterm's CI checks its mirror of this file against this one and runs the same steps against its own client, so a verb reshaped on either side fails the other product's build. That is the difference between a promise and a gate.

Shape, not values: "session.text returns a string" is a contract; "it returns exactly these bytes" is a snapshot of one machine's shell prompt. Extra fields are allowed; the named ones must be present.

It found three real divergences on its first run

	agwinterm	agliteterm
window.list	{"windows":[…]}	a bare array
window.state	UI flags — sidebarVisible, fullscreen, maximized, quickTerminalVisible, activeWorkspace, activeSession	window geometry

Every script that reads .result.windows breaks against agliteterm's shape, and window.state was two different verbs wearing the same name. Both fixed on the agliteterm side (geometry kept as extra fields), which is where the deviation was.

The third is on this side and is now written down rather than fixed: session.new returns an id before the session exists. The full app posts the creation to its UI thread and answers immediately, so a verb aimed at that id a millisecond later legitimately cannot find it. The spec settles between the two; the wart is documented in the step's note.

Two traps in the harness, both of which produce confident wrong answers

• agwintermctl defaults its target to $AGWINTERM_SESSION_ID. A suite run from inside a terminal session therefore aims untargeted verbs at the developer's session, which the sandbox instance has never heard of. Six checks failed for that reason before the runner started clearing those variables — and on a bare CI runner it would have passed, so the local and CI results would have disagreed with no explanation.
• Content verbs follow the frontmost window. All the full app's windows share one process, so window.select in the middle of the run silently redirected the later session and workspace verbs to a host that had never heard of their ids. The spec now does lifecycle first and windows last, and says why — the failure looks exactly like a contract break.

Neither is a possibility in agliteterm, where every window is its own process with its own pipe. That asymmetry is itself part of what the contract has to survive.

The env contract

AGWINTERM_ENABLED / PIPE / SESSION_ID / PANE_ID are checked by asking the shell, not the app — what matters is that the child process actually received them. That prefix is the reason the rename kept it, so it belongs in the contract rather than in an implementation note.

Verification

All 39 steps green against the full app, and green against agliteterm after its two fixes. Locally run against an installed 0.17.3 and a fresh agliteterm build.

One thing this PR cannot answer: whether a GitHub runner can host a suite that creates real windows and real shells. These checks have only ever run on a developer machine. The first CI run is where we find out — if the runner can't, the step is the thing to change, not the contract.

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

🤖 Generated with Claude Code