fix(ios): deny viewport during capability admission on Apple targets

[thymikee]

Summary

viewport was admitted by the capability matrix on every Apple simulator and physical device, but no Apple interactor implements setViewport. The command was therefore routed all the way to the device and rejected inside dispatch with a backend-shaped error. Nothing can serve it there — Apple screen geometry is fixed by the selected device type, and neither simctl nor XCTest exposes a resize primitive — so viewport is a web-surface contract, which is what its CLI summary ("Resize the active web viewport for the current session") and every doc example (--platform web) already say.

This denies viewport during capability admission for Apple targets, matching the Android denial on the adjacent line of the same descriptor, and gives the Apple family an unsupported hint that names the surface that does support it.

Before, on a booted iOS simulator:

$ agent-device viewport 390 844 --json
"code": "UNSUPPORTED_OPERATION",
"message": "viewport is not supported by this backend",
"hint": "This command is not available for the selected platform/device.",
"supportedOn": "apple, web"

After:

$ agent-device viewport 390 844 --json
"code": "UNSUPPORTED_OPERATION",
"message": "viewport is not supported on this device",
"hint": "viewport resizes web targets only (--platform web). Apple screen geometry is fixed by the selected simulator or device type — open a different simulator to test another screen size.",
"supportedOn": "web"

capabilities no longer advertises viewport on Apple targets. Web viewport resizing (agent-device viewport 1280 900 --platform web) is unchanged, and Android was already denied.

Coverage moves with the behavior: the iOS simulator coverage manifest's known-gap row becomes a capability-denial row owned by the static coverage test (the same shape tv-remote uses). That was the only known-gap row, so the known-gap level and the full:known-gaps live scenario — which existed solely to run viewport 390 844 on a real simulator and assert it fails — are retired with it. The denial and its hint are now pinned by capabilities.test.ts, both independent Apple capability-parity oracles, and the simulator coverage test.

Closes #1407

Validation

Live on a booted iPhone 17 Pro simulator (iOS 26.2), before/after against builds of the same worktree: the before run's request diagnostics show platform_command_prepare → platform_command → request_failed, i.e. the request reached the Apple interactor; the after run shows request_start → request_failed only, so admission now rejects it before the device is touched. capabilities output confirms viewport disappeared from the simulator's admitted set. The verification session was opened and closed with an isolated --state-dir, and its daemon stopped.

The web path was not exercised live — the managed agent-browser backend is not installed on this host — so web coverage here is web-desktop.test.ts (green, asserts the set viewport 1280 900 provider call) plus the web column of capabilities.test.ts.

Unit suite, typecheck/lint/build/layering/MCP-metadata, fallow (clean on all 11 changed files), and the iOS simulator coverage smoke suite pass. provider-scenarios/android-test-suite.test.ts fails 3-6 timeout-shaped tests with a shifting failure set on this host; it reproduces identically with these changes stashed, so it is host contention, not this change. GitHub remains authoritative.

Notes

11 files touched, all within the viewport command family and its coverage manifests. No docs update was needed: the command surface, CLI help, and website/docs already describe viewport as web-only — this change makes capability admission agree with them. CHANGELOG updated under Unreleased.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.90 MB	1.90 MB	+231 B
JS gzip	609.8 kB	609.9 kB	+108 B
npm tarball	727.6 kB	727.7 kB	+87 B
npm unpacked	2.55 MB	2.55 MB	+231 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	27.5 ms	26.8 ms	-0.7 ms
CLI --help	60.6 ms	56.3 ms	-4.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/sdk-batch-runner.js	+1 B	+1 B

[thymikee]

Reviewed 9919b881: clean. viewport is now denied during Apple capability admission, while the web-only bucket remains unchanged; generic dispatch therefore rejects before the Apple interactor. The Apple-specific hint and supportedOn: web are pinned by independent capability/plugin parity tests, and the simulator coverage manifest correctly replaces the retired dispatch-gap scenario with capability-denial evidence. The reported simulator before/after diagnostic path is consistent with this route. Required Android/iOS smoke and Swift runner jobs are still in progress; no failures are currently reported. Residual risk: no separately authorized cross-vendor pass.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-30 18:22 UTC