feat(computer-use): add maka-cu as a selectable executor backend

[hqhq1025]

What this adds

maka-cu is a Maka-owned native macOS Computer Use executor. It speaks the
maka.cu/2 host protocol over stdio JSON-RPC, and this PR adds the host side of
that conversation: a CuDispatchBackend implementation, the protocol readers,
the child-process supervisor, and the script that builds the executor from source
and pins its digest.

Why it exists

The executor Maka ships against today re-resolves what the model pointed at. The
host hands down an element index, the executor walks the tree it can see now, and
if the window changed in between, the action lands somewhere else — or lands
nowhere and reports that it landed.

maka.cu/2 moves frame binding into the executor. A dispatch quotes three
things: the snapshot id, the element token, and the digest the host was given for
that token. The executor compares them against the tree it minted and answers in
a closed vocabulary — snapshot_spent, element_changed, element_released,
process_replaced — instead of guessing. That is why this backend has no
re-match pass, no occlusion geometry, and no path inference: it carries identity
down and maps declared answers back.

Two consequences follow from owning the executor rather than consuming one.
Waiting for a launched app's first window happens inside the executor, which is
where the information is, so launch_app stops returning an empty window array
that costs the model a whole extra observe cycle. And a refusal arrives as an
enum with a path and an effect, so the host can tell a model that its action was
attempted and declined apart from one that could never have reached the target.

What this PR does not do

It changes no default. selectComputerUseBackend returns cua-driver for every
caller that does not pass backendId: 'maka-cu', and no caller in this
repository passes it. It deletes nothing belonging to cua-driver: the backend,
its service, its page-target resolver, its snapshot readers, its provenance
script and its bundled-tools entry are all untouched.

The follow-up PRs in the chain are, in order: switch the desktop host to select
maka-cu, then remove cua-driver.

Contract surface

The executor answers more about a tree than Maka's shared Computer Use contract
has fields for — per-element placeholder text, subrole and advertised actions,
whether the walk was truncated, the menu scope, what is stacked over the target
window — and it can carry out window and scroll actions that the tool schema
cannot yet express. Rather than widen CuObservation, CuObservedElement and
CuSemanticAction with members no tool can produce and no renderer reads, those
widenings are local to @maka/computer-use. Structurally a MakaCuObservation
is a CuObservation, so nothing downstream changes; the PR that gives these a
model-facing home is the one that moves the declarations up.

One shared change was unavoidable: dispatch_refused joins
COMPUTER_USE_ERROR_CODES. It cannot be local because the union is closed, and
it cannot be folded into a neighbour without losing the distinction the model
acts on. capture_failed names the wrong subsystem, and unsupported_action is
where "the element does not offer this" already lands. "It offered it, we tried,
the OS said no" is a different next move.

apps/desktop/src/main/capability-snapshot.ts changed because the backend id it
reports is no longer a single-member union. The capability now reads "available"
for any selected executor instead of for one named executor, which is what it
meant all along.

Testing

Covered by tests that run in CI:

• packages/computer-use/src/__tests__/maka-cu-protocol.test.ts — every reader
  refuses a malformed or incomplete envelope rather than defaulting a missing
  field. A declared field that is absent is version skew and has to be caught at
  the boundary.
• packages/computer-use/src/__tests__/maka-cu-backend.test.ts — 60-odd cases
  against a scripted executor: frame binding and its four release reasons,
  session lifecycle and restart, the refusal vocabulary and the sentence each
  refusal gives the model, key chord parsing including the Object.prototype
  spellings that used to parse into a chord with a non-string key, image
  handling, abort propagation, and the truncation and occlusion fields.
• scripts/computer-use-provenance.test.mjs — a rot guard on
  docs/computer-use-provenance.md: every repository path the record names must
  exist, its three sections must stay separate, and the manifest must agree with
  what the record claims about each executor.
• Backend selection: that naming maka-cu selects it, that omitting the digest
  yields 'none' rather than a backend willing to spawn whatever is at the path,
  and that a caller who names nothing still gets cua-driver.

Not covered here, needs a real machine:

• Everything the executor actually does against macOS Accessibility. The tests
  above talk to a scripted process over the same pipe, which proves the host
  reads the protocol correctly and proves nothing about AX behaviour.
• The two selection tests are macOS-only by an explicit process.platform check
  and do not execute on the Linux CI runner.
• TCC identity. The executor is built from source and left ad-hoc signed, so
  macOS identifies it by its code directory hash and Accessibility has to be
  granted again after every rebuild. MAKA_CU_SIGN_IDENTITY makes the grant
  survive; there is no notarized artifact yet.
• Distribution. distributionReady is false and
  scripts/verify-macos-arm64-dmg.mjs now forbids the binary's path in a
  packaged build, so this executor runs in a development build only.

[hqhq1025]

Review findings addressed, and the branch is rebased onto current main.

The rebase was clean, one commit replayed with no conflicts. That is what brings computer-use-schema-parity into this branch's test run — the old merge base was one commit before it landed, so the check that walks the wire schema and the strict union against each other was not running on this branch at all.

focused reached the observation through a spread into an object literal, which is the one form of object construction TypeScript does not excess-property check. No type declared it, so there was no compile-time link between emitting it and the layer that renders it. It is declared on MakaCuObservedElement now, beside the other fields carried past the shared type.

selectedText was declared on the element as a bare string. The protocol carries it per snapshot as text plus whether it was cut, and nothing ever assigned it, so the file's header listed it among the four things this backend carries and it carried none of it. It moves to the observation in the shape the wire declares, and is assigned. The mock executor grew an env switch so a snapshot can actually carry one.

readDispatchResult had no test at all and now has one for each of its three closed sets and both of its cross-checks.

One correction to the finding as filed. Replacing the path requireMember with an unchecked cast does not let an unknown path through. Every non-member is refused two lines later by the tier/path pairing check, because no non-member appears in any tier's list, and the only path that skips that check is none, which is a member. I probed all seven bad values against all three tiers with the cast in place and every one was refused. What the cast actually changes is which reader says no and therefore what the message names, so the assertion is on that: a maka-cu version bump that renames a path should read as version skew in the field it renamed, not as a tier mismatch that never happened.

Negative controls, each one run.

Removing the path requireMember, with the message assertion in place:

✖ failing tests:
✖ refuses a path that is not in the closed set

Replacing the tier requireMember with an unchecked cast, which has no backstop at all — PATHS_BY_TIER[tier] is undefined and the next line throws a TypeError rather than a protocol violation:

✖ failing tests:
✖ refuses a tier and an outcome outside their own closed sets

Dropping the tier/path pairing check:

✖ failing tests:
✖ refuses a path its tier does not permit, and a global-pointer path that was not granted

Dropping the focused spread and the selectedText assignment:

✖ failing tests:
✖ carries which element is focused, from a declaration rather than a spread
✖ carries the selected text in the shape the wire declares

Restored, the file is 16 pass 0 fail for the protocol suite and 73 pass 0 fail for the backend suite, and @maka/computer-use is 224 pass 0 fail.

Full suite on this branch: core, mcp, ui, desktop and computer-use all pass. runtime, storage, cli and runtime-host fail on the usual environmental set — PTY spawn and shell streaming under load, macOS /private/var realpath, and node:sqlite — in eighteen files, none of which this branch touches. Re-running them in isolation clears all but the known workspace-executor PTY one.

Merge-order note that still stands: this should land before #1952. Both add dispatch_refused to COMPUTER_USE_ERROR_CODES at different positions, so whichever merges second should drop its own.

[hqhq1025]

Third-round review findings addressed in ab1e520. Everything below was verified by execution before it was changed, and every new assertion was negative-controlled by reverting the fix, rebuilding, and observing it go red.

1. Fixed. A bare null line on the child's stdout. Reproduced against the built service with a fake executor: UNCAUGHT: TypeError Cannot read properties of null (reading 'id'), exit 7. decodeJsonLines hands onMessage any JSON value, and the read happens inside a stdout data listener where no caller is on the stack. Non-record values are now counted under the same budget as a line that is not JSON at all, so three of them still tear the generation down as a protocol violation rather than being silently dropped. Same script after the fix: SURVIVED: the null line did not crash the host, exit 0.

2. Fixed. readLimits now reads all nine fields as whole numbers of at least 1, thrown as MakaCuProtocolViolation. Executed against the built service:

baseline (all sane)      ACCEPTED snapshotsPerSession=8
snapshotsPerSession: 0   REFUSED  MakaCuProtocolViolation: limits.snapshotsPerSession must be at least 1, got 0 (generation=1, state=unavailable)
snapshotTtlMs: -1        REFUSED  MakaCuProtocolViolation: limits.snapshotTtlMs must be at least 1, got -1 (generation=1, state=unavailable)
shutdownGraceMs: 0       REFUSED  MakaCuProtocolViolation: limits.shutdownGraceMs must be at least 1, got 0 (generation=1, state=unavailable)
maxElements: 2.5         REFUSED  MakaCuProtocolViolation: limits.maxElements is not a whole number (generation=1, state=unavailable)

generation=1 is the point: one spawn, not three. On the six unread fields, maxResponseBytes now sizes the stdout budget (which also answers the 4 MiB cap in finding 9), and the comment claiming every field had a host consumer has been replaced with one naming the five that do not. Wiring maxElements or settleCeilingMs would have meant inventing host behaviour to justify the sentence, which is the wrong direction.

3. Fixed. computerUseServiceHealth now takes either shape and boot.ts reads serviceState?.() ?? executorState?.(). Its reasons name the selected backend instead of hardcoding cua-driver. The negative control here is a compile error, which is the strongest form it could take: with the function reverted, boot.ts fails with Argument of type 'MakaCuServiceSnapshot | { action; capture } | undefined' is not assignable, and Type 'MakaCuServiceSnapshot' is missing the following properties: action, capture. Nothing in this change selects an executor.

4. Fixed, all four parts. postObservationError.code is held to §7.1's table with requireMember, and the executor's message no longer reaches the model at all — it goes to the trace and the model reads a sentence keyed by the code. detail.wouldRequirePath is held to MAKA_CU_DISPATCH_PATHS in readEnvelope. element.actions[] is held to a §5 set exported from the protocol, and the dispatcher's list is now derived from that same set minus scroll_to_visible, so an observation can no longer advertise a name the dispatcher would refuse. And nextMoveFor no longer leads with error.message: messageIsAppTextFree: true was being asserted over a string that came off the wire, and there was no way for the host to check it. The refusal sentences are a table keyed on the codes §7.1 can produce, checked total at compile time, so a new row in the mapping table without a sentence does not build.

5. Fixed. The handshake readers throw MakaCuProtocolViolation, and startWithBudget treats it as fatal along with a version mismatch and an unusable executable. The generation=1 in the finding 2 output is the evidence.

6. Fixed, with a judgement call. Settling an aborted delivered request as aborted would be a lie: it may already have driven the screen. What was wrong was waiting the full request deadline for an answer. There is now a bounded cancel grace: $/cancel goes out, the executor gets a short window to answer with the action's real fate, and if it does not the request is torn down the way an unanswered deadline is. Test asserts the caller settles well inside the grace rather than at the deadline; before the fix that test took 8070ms against an 8s deadline.

7. Fixed by the same mechanism. The timeout path no longer kills in the same tick as the notify, so $/cancel reaches the child. Asserted by reading the mock's own receive log on the timeout path, which was empty before.

8. Fixed, except one part. child.on('error') keeps its Error and an exec that never happened is reported as one for every stage, since a write that resolves against a pipe with no process behind it delivered nothing. Every host-initiated kill now has its own sentence — framing overflow is protocol_violation rather than child_exit, and dispose() says the host shut it down. restartAttempts still only resets on success, but the reason is remembered on the instance, so later calls carry it. The pre-fix outputs, captured from the negative control run, are exactly what was described:

actual: 'service_unavailable: maka-cu restart budget exhausted: outcome_unknown: maka-cu exited after request delivery'
expected: /could not be executed/
actual: 'service_unavailable: maka-cu restart budget exhausted: undefined'

verifyExecutable now codes ENOENT/EACCES as service_unavailable naming the path, and keeps service_mismatch for the sha256 case, which is the only mismatch in that method; both are fatal, so neither burns the restart budget. Not done: moving it from the first tool call to selection time. Selection is synchronous and this is not, so that is a shape change to selectComputerUseBackend rather than a fix, and it belongs with whatever makes maka-cu selectable.

9. Fixed, four of five. dispose() captures starting before setting disposed and purges again when it settles, which is cua-driver's guard that this copy dropped. MAX_STDOUT_BUFFER is now derived from maxResponseBytes. limits() throws a host refusal instead of a plain Error, so a child that dies between the handshake and the response answers the tool call rather than escaping the CuRunResult contract. requireSnapshot distinguishes expired, evicted, spent, superseded and never-minted, since the host is the one that forgot the id and knows which; the reasons are kept in a map capped at 256 entries. On clearSession: it now cancels that session's in-flight work rather than SIGKILLing the child, so the other sessions survive and session.end actually gets sent. The negative control caught this one: with the old code the test read actual: 'idle', expected: 'ready'.

10. Added. packages/computer-use/src/__tests__/maka-cu-service.test.ts, 17 cases in 5 groups: what the child may put on stdout (non-response JSON, the three-line budget, the negotiated stdout cap), the handshake as a closed contract (five rejected limit shapes plus an accepted one), cancelling a delivered request (grace not deadline, the executor's own answer, the deadline's cancel reaching the child, one session cleared without ending the others), the failure reports (exec failure, absent binary, exhausted budget), and the shutdown purge. Reverting maka-cu-service.ts to e4d2442 and rebuilding turns 16 of the 17 red. The one that stays green is the executor answering its own cancel, which was already correct by design and is a characterisation test rather than a regression test.

11. Fixed by correcting two docstrings and making the third true. frame-budget.ts now is the one budget, because cua-driver-backend.ts imports exceedsFrameCap and FRAME_COMPRESS_THRESHOLD_BYTES instead of keeping private copies with matching values — same numbers, no behaviour change. abortable-delay.ts now says only maka-cu uses it and names the cua-driver wait bug it does not fix; fixing that is a behaviour change on the default backend and does not belong in this PR. The obscuringRects comment says it is carried and read by nothing, since neither frontmost nor destinationCovered exists anywhere in the tree.

Nothing on this branch makes maka-cu reachable. DEFAULT_CU_BACKEND_ID is still cua-driver, selectComputerUseBackend still requires backendId: 'maka-cu' by name, and the only callers that pass it are tests. createComputerUseHost still selects without a backendId.

Verification: npm --workspace @maka/computer-use run test:dist is 244/244. The four desktop Computer Use suites are 9/9. npx biome check is clean over all ten touched files and node scripts/check-console.mjs passes. The full parallel workspace run shows failures in runtime, runtime-host, storage, cli and desktop; all of them are shell, PTY, UDS and filesystem tests, one reports SANDBOX_FILESYSTEM_OPERATION_FAILED, none touch computer-use, and each is green when re-run in isolation.