Skip to content

docs(rfc): carry remote computer use on the connected-computer socket - #40207

Open
unstablebrainiac wants to merge 1 commit into
mainfrom
unstablebrainiac/docs/remote-cu-connected-computers
Open

unstablebrainiac wants to merge 1 commit into
mainfrom
unstablebrainiac/docs/remote-cu-connected-computers

Conversation

@unstablebrainiac

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Revise the remote Computer Use RFC so a Linux gateway drives a connected Mac over the connected-computer socket main already has, without a transport of its own and without hiding a local Linux driver.

RFC #21981 (docs/request-for-change/rfc-remote-computer-use.md, status draft) was written before connected computers existed. It gave the Mac its own scoped bearer credential, six pull routes through the tunnel and an Electron channel. Since then the gateway half of connected computers landed (#34858): one authenticated socket per computer, dialled out over the same SSH forward, with a credential minted over the same SSH login. Built as written, the RFC would add a second tunnelled credential scheme for the same Mac. It also says nothing about a Linux gateway that has a local driver, which #35378 and #25222 propose.

Why it matters

The RFC is the design every implementation PR for remote Computer Use cites. A design that duplicates connected computers' transport, or that would swap out a working local Linux driver, would be argued over in each implementation PR instead of once here.

Not a goal

  • Accepting the RFC. The status stays draft; a maintainer records acceptance.
  • Any code. No implementation PR is opened by this change.
  • Changing connected computers' protocol or connector. The RFC asks its author for those changes as open questions.
  • A Linux driver, Windows executors, or remote executors for a macOS gateway.

What changed (motivation → approach → change)

Revision 2 of the RFC keeps the parts that do not depend on the transport and moves the transport onto connected computers.

Part Revision 1 Revision 2
Transport Six pull routes and a bearer credential of its own A computer-use channel on the Mac's connected-computer socket; no new route or credential
Mac key A Mac switch bound to the SSH host key plus a new installation id A "use this Mac's desktop" capability on the Mac's own connected-computer grant
When the remote path appears Every Linux gateway Only while a Mac is enrolled with that capability
Linux with a local driver Not covered The local driver stays the default
Wire, Mac floors, failure codes As designed Unchanged

The RFC names what it needs from connected computers (a channel kind, a folder-less grant, a host-scoped channel, one confinement exemption for the fixed executor program) and asks those as open questions for the feature's author. Revision 1's own transport stays, condensed, as the fallback if a maintainer rules that Computer Use must not depend on connected computers. The phases are reordered so the backend seam, the codec, the Mac executor and the forwarding backend can land before any of connected computers' open PRs. The RFC index row and its audit note in docs/request-for-change/README.md describe revision 2.

Backwards compatibility

Compatible: documentation only; no code, config or route changes.

Removes nothing: the RFC's revision 1 transport is kept as its fallback section, and no code exists for it.

Tests

N/A -- docs only. python3 scripts/docs_lint.py exits 0, and the comment-history and brand checks pass.

Proof: not provable -- docs or config only

Manual verification

N/A -- docs only. Every code claim in the RFC was re-read on main 1c37e326a2.

Real-machine verification

N/A -- the diff changes two Markdown files and runs nothing.

Related Issues

Part of #40197

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 20, 2026
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change is a draft RFC revision in documentation only, it is reversible, and it adds no new governance row or pointer permit.

Notes

  • The confinement exemption for the fixed kirocrew computer executor argv is the load-bearing security decision here. Open question 7 should get a ruling from the owner of connected computers before Phase 1 code cites this RFC.

[DESIGN-REVIEWED] 2eff5db

Description read

[DESCRIPTION-READ] f1f8d814569ca406672e645a9cecc5204f354a551b6f527946bf1b4a6f7d2135

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • The RFC leaves a Linux gateway's keystone switched on after its last paired Mac is revoked. Settings then shows LINUX_REASON with no toggle, but _computer_use_spec_gate keeps advertising the tools. It is worth naming this in the RFC's open questions.

[OPUS-REVIEWED] 2eff5db

Verdict parsed from the review's SHA-scoped output markers for commit 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2eff5db

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2eff5db901e5fd0f7a2220a9ee1d064e459cdb3e false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 21, 2026
@unstablebrainiac
unstablebrainiac enabled auto-merge (squash) November 21, 2026 00:46
@KiroCrewCaptain

KiroCrewCaptain commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 994 lines, more than the 400 it may approve on its own.

Docs-only revision 2 of a draft RFC; status stays draft. I checked its code claims about connected computers against the repo and they match: protocol v1 with required root and confinement in ready, kind_of, frame/window/heartbeat/deadline limits, broker.open, MAX_CONNECTION_CHANNELS, flag.remote_refusal, the connect path and the spec gate's platform check. The trust design holds: no new credential or route; a downgrade can only drop the desktop option; the RFC admits the keystone proves nothing against a compromised gateway, and the Mac re-runs the floors on records it resolved itself. The riskiest choices (no folder confinement for the executor, agent self-enrollment, killing child processes when the socket ends) are left as open questions for the feature owner. The README row is consistent with the RFC. CI and review lanes are green.

Tier: 2, held for a person: design-doc-gate: D.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 2eff5db901 · 994 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This adds a new concept, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.
To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result on this head: no blocking findings. The diff touches only two Markdown files, and the RFC stays draft. We checked the RFC's code citations against main, and they hold. They include the protocol constants and the exact-version check in decode, the ready field shape, the connector token audience and TTL, and the secure-target tool set. We also checked check_input_target and _same_identity. scripts/docs_lint.py passed on the head tree. One thing done well: the revision drops a whole second credential scheme. The executor now rides the connector socket, which is already authenticated, and the RFC names each thing it needs from connected computers as an open question for that feature's owner.

For the security review (the decision on these stays with the security reviewer and the maintainers):

  • The design exempts the Mac executor from connected-computer confinement, and it adds a grant with no folder. Both widen what a connected computer can do today.
  • The protocol v2 negotiation rests on an unauthenticated hello.v and features header. Only ready is inside the session MAC. The RFC argues that a relay can only downgrade, and a downgrade fails closed. That argument needs a security review.
  • The Mac "allow moving my pointer" option is a pointer permit. The root AGENTS.md rules for Computer Use forbid pointer permits, and the option breaks Goal 1's parity with a local macOS gateway. Either drop it, or keep it as a stated trust-boundary exception and add it as an open question.

Optional:

  • §3 "Paired" reads a desktop capability from the device record, but DeviceRecord has no such field, and ready cannot be sent twice on one connection. Say how the gateway's view stays current after sleep, a reconnect or a capability toggle. Today the executor_ambiguous remedy and Phase 4's "the next call returns no_executor" have no mechanism behind them.
  • The connector's 5 second ping shares the executor's stdin stream with channel data. One request line can span data frames, and ping is not in the closed verb table. Add ping to the table and insert it only at a line boundary, or give the watchdog its own pipe.

@unstablebrainiac
unstablebrainiac force-pushed the unstablebrainiac/docs/remote-cu-connected-computers branch from 8a1b513 to 2eff5db Compare November 21, 2026 01:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants