Skip to content

fix(runner): type the refusals for a control the target cannot supply - #4548

Merged
thymikee merged 5 commits into
mainfrom
fix/typed-unsupported-refusals
Nov 15, 2026
Merged

thymikee merged 5 commits into
mainfrom
fix/typed-unsupported-refusals

Conversation

@thymikee

@thymikee thymikee commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

Four refusals answered a generic code plus prose, so a caller could tell which one it got only by reading message. Each now answers with the runner's own code; the host maps it to the code its command already refused with and publishes details.reason. Public codes are unchanged (19 files).

Refusal details.reason dispatched code
keyboard enter, no return key and no field keyboard_return_unavailable unknown (sole-field route taps before typing) UNSUPPORTED_OPERATION
Action Button on a model without one hardware_control_unavailable no UNSUPPORTED_OPERATION
macOS back, no in-app back control in_app_back_control_unavailable no COMMAND_FAILED (what the code-less reply had)
Android keyboard dismiss, IME ignored escape keyboard_dismiss_unavailable (one reason across platforms) unknown (keyevents sent) UNSUPPORTED_OPERATION

iOS keyboard dismiss with no dismiss key was already typed by #4536; skipped. Simulator volume and non-tvOS remote presses are refused by runtime admission before the runner, so they keep unsupported-device-kind / unsupported-platform-leaf — the prose names the reachable route only. No issue was filed.

Validation

Base d78be6c887, tested head 93dc052e06.

  • vitest --project apple-runner 967 passed; unit-core (src/__tests__ src/commands packages/command-output) 3923 passed, 2 skipped; repo-guards, command-surface, platform-android, schema passed.
  • tsc -b tsconfig.typecheck.json clean; pnpm format/lint clean; check:xctest-selection clean (722 methods, 0 unreachable).
  • macOS host XCTest lane (test-without-building, -skip-testing:.../testCommand) at 1d453224ed: 433 tests, 0 failures, including both new refusal tests. Swift is comment-only since that SHA.

Unresolved: iOS-simulator and tvOS lanes for the new codes are CI's; the Action Button emission site has no Swift falsifier (deferred, comment-only diff since).

Guard

test/repo-guards/runner-refusal-reason-docs.test.ts fails if a reason joins the union without appearing in commands.md.

🤖 Generated with Claude Code


Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff Turn on auto-fix

thymikee and others added 4 commits November 14, 2026 12:36
Four refusals answered with a generic code and prose, so a caller could tell
which one it got only by reading `message`. Each now answers with the runner's
own code, which the host maps to the code its command already refused with and
publishes as `details.reason`.

`keyboard enter` with no return key and no field to submit through reports
KEYBOARD_RETURN_UNAVAILABLE under UNSUPPORTED_OPERATION. Its disclosure stays
`unknown`: the sole-text-field route taps that field before typing the return,
and that tap can be the step that fails. A press of a control this target
cannot express reports HARDWARE_CONTROL_UNAVAILABLE under
UNSUPPORTED_OPERATION with `dispatched: no` — the Action Button on a model
without one, a volume key on a simulator, or a Siri Remote button off tvOS all
press nothing, and the message names the control. macOS `back` finding no
in-app back control reports IN_APP_BACK_CONTROL_UNAVAILABLE; it keeps
COMMAND_FAILED, the code its code-less reply always produced, and
`dispatched: no`. One reason covers Android's keyboard dismiss too:
`keyboard_dismiss_unavailable` with `dispatched: unknown`, because its escape
keyevents were already sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The classifier publishes details.reason from a code, and the doc is prose a
reader follows, so nothing connected the RunnerReportedErrorReason union to
website/docs/docs/commands.md. A reason added to the union and not published
would reach clients as an undocumented value they cannot branch on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Runtime admission refuses an iOS Simulator volume press and a non-tvOS remote
press before the runner is asked, under `unsupported-device-kind` and
`unsupported-platform-leaf`. The published prose named this new runner code for
those routes, where a caller would key on a reason that can never arrive. It
now names the code for the press the runner does answer — the Action Button on
an iPhone or iPad model without one — and the command help carries it too. The
keyboard help attributed Android's keyevents to iOS, and each new classifier
test lacked the closest negative: prose alone earning no reason.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The guard collected quoted snake-case literals with a regular expression, so a
member that is not one — a digit, a hyphen, or a non-literal member — dropped
out of the doc check instead of failing it. Silence is the failure mode the
guard exists to prevent. It now walks the union with the parser the sibling
startup-reason guard uses and rejects every member it cannot read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.28 MB 6.28 MB +2.3 kB
Package (unpacked) 6.28 MB 6.28 MB +2.3 kB
Package (download) 1.90 MB 1.90 MB +640 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 20.1 ms 19.6 ms -0.5 ms
CLI --help 38.1 ms 41.9 ms +3.8 ms

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 19 files

You’re at about 90% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread apple/runner/RUNNER_PROTOCOL.md Resolved
Trim the action-button searchHint, document the reachable hardware refusal sites, match refusal reasons as whole tokens, split the keyboard enter field-attempt failure from the missing-control refusal, and count the Android escape keyevents in the disclosure row.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve

No open findings.

2 findings below minor hidden (user_settings.min_severity).

Reviewed with this repository's own Sentinel configuration (d78be6c88715).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

This looks ready at 2002e0a. I found nothing that needs to change before merge.

CI is green: 22 checks, none failing, including the Apple smoke jobs that build the changed Swift. There are no conflicts. Nothing else blocks merge.

Not blocking, so take or leave each: testKeyboardReturnFieldAttemptFailureIsNotTheTypedRefusal only asserts that two constants differ, so it would still pass if fieldAttempted stayed false on the sole-field route. Could the choice at CommandExecution.swift:625 move into a pure keyboardReturnFailure(fieldAttempted:) that the test checks for both arms? The PR body says Swift is comment-only since 1d45322, but the diff since then adds the fieldAttempted logic and a new unit test, so the Validation section could name the head the host lane ran at, or point to CI's Apple jobs for that split. The action-button searchHint changed from 'hardware' to 'side switch' at system/index.ts:737, which means a search for 'hardware' no longer finds it. The new remotePress hint says 'On a TV target use tv-remote' at CommandExecution.swift:431, but that refusal fires only off tvOS, where tv-remote is refused too. The Android keyboard_dismiss_unavailable literal at device-input-state.ts:42 is tied to the Apple union only by a comment, so a rename on one side would drift silently.

On the earlier inline threads: none of them still apply at this head, so they can be resolved. #4548 (comment) (RUNNER_PROTOCOL.md) now names all three emission sites. #4548 (comment) (docs reason matching) now uses whole-token lookarounds with prefix and suffix tests. #4548 (comment) (keyboard description) now limits the iOS reason to the no-key case. #4548 (comment) (fieldAttempted split) is fixed in code, and the test gap is in my note above. #4548 (comment) (escape key count) is now asserted before the rethrow.

I ran no tests. I could not confirm that CI's Apple selector ran the iOS-only keyboard test for nothing focused, which the macOS host lane does not cover, and the Action Button site has no Swift test, so I checked that change by reading.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 14, 2026
@thymikee
thymikee merged commit 9f78c23 into main Nov 15, 2026
22 checks passed
@thymikee
thymikee deleted the fix/typed-unsupported-refusals branch November 15, 2026 07:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant