Implement v1 read-only Crabbox iOS coordinator companion

[zozo123]

Summary

PR #379 proved there is plausible implementation energy for a native mobile client, but it was closed unmerged on 2026-07-01 because the branch combined too many ownership decisions for one merge contract: product direction, mobile credentials, persistent web session/security, direct-provider behavior, marketplace/payment direction, and permanent Swift/Xcode/mobile CI.

This issue is the requested focused design/roadmap decision. It should decide whether Crabbox wants a first-party mobile client at all, and if yes, what the first shippable slice is.

Recommendation

Start with the narrowest useful mobile companion:

• SwiftUI shell plus a testable shared core only for URL/policy/state logic.
• Portal/coordinator-oriented workflows first.
• No direct provider API keys in the app for v1.
• No direct islo/OpenComputer/OpenSandbox/etc. lifecycle from the device for v1.
• No marketplace/payment, on-device LLM, sandbox LLM, map-reduce demo, Android assets, or broad CI ownership in the first PR.
• CI only proves the accepted slice: Swift package tests plus unsigned iOS build. Device/simulator proof is required only for the UX flows that ship.

This keeps the branch in the mobile product decision lane instead of creating a new provider/security boundary immediately.

Decisions to make

• Is a first-party mobile client in scope for Crabbox?
• Which v1 slice do maintainers want?
  • Portal companion: authenticated portal/workspace access, status/read-only views, minimal native shell.
  • Coordinator run companion: launch/list/status/stop through the existing coordinator only.
  • Direct provider client: iOS stores provider credentials and calls provider APIs directly.
  • Portable core only: merge reusable CrabboxKit pieces without an app target yet.
• Who owns mobile product UX?
• Who owns mobile credential/session security review?
• Who owns Swift/Xcode/mobile CI and release maintenance?
• What visual proof is required for the accepted v1 slice?

Suggested acceptance criteria

• A maintainer chooses one v1 scope and explicit non-goals.
• Security model is written down before implementation, including where tokens/session state live and which URLs are trusted.
• CI contract is written down before implementation, including whether macOS/iOS jobs are required on every PR.
• A fresh PR is cut from current main after this issue is accepted.
• The fresh PR does not inherit unrelated surfaces from PR feat: native SwiftUI Crabbox iOS app (crabbox.sh client + on-device/sandbox LLM + islo) #379 unless this issue explicitly includes them.

Non-goals until explicitly accepted

• Direct provider API-key storage in iOS Keychain.
• Persistent WebView session ownership beyond the accepted portal/auth design.
• Direct islo/OpenComputer/OpenSandbox sandbox lifecycle calls from the app.
• Marketplace/payment direction.
• On-device MLX/Foundation Models or sandbox LLM chat.
• Map-reduce demo flows.
• Android/app-store distribution.
• Keeping the closed 8k-line branch rebasing indefinitely.

References

• Closed exploratory PR: feat: native SwiftUI Crabbox iOS app (crabbox.sh client + on-device/sandbox LLM + islo) #379
• Maintainer close rationale: feat: native SwiftUI Crabbox iOS app (crabbox.sh client + on-device/sandbox LLM + islo) #379 (comment)
• Last PR head with working proof artifacts: 605571fd32e41ae087fa22427f0a835a32ab51ad

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 31, 2026, 2:31 AM ET / 06:31 UTC.

Summary
Keep open: this issue remains the accepted implementation contract for a first-party, read-only iOS coordinator companion. The merged pairing backend is a prerequisite, not the native SwiftUI client; the companion, simulator/device proof, and the pre-broad-release security hardening still remain.

Reproducibility: not applicable. this is an accepted feature implementation request, not a report of broken existing behavior. The current-main and discussion evidence establish that the backend prerequisite exists while the native client does not.

Root-cause cluster
Relationship: canonical
Canonical: #778
Summary: This issue is the canonical remaining implementation track for the accepted native companion; the merged pairing PR is a prerequisite and the open security item is a related pre-release hardening track.

Members:

• fixed_by_candidate: feat(worker): add read-only device pairing #1199 - Merged server-side pairing, scoped device credentials, redacted lease reads, and destructive-route rejection needed by the companion, but did not add the iOS app.
• partial_overlap: Device tokens: reduce OAuth credential retention and membership-check amplification #1200 - Tracks security hardening of the device-token backend that must be addressed before broad companion availability, not the native client implementation itself.
• superseded: feat: native SwiftUI Crabbox iOS app (crabbox.sh client + on-device/sandbox LLM + islo) #379 - The closed exploratory branch bundled direct-provider, marketplace, LLM, and mobile-CI decisions that the accepted v1 contract expressly excludes.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Include the exact command, prompt, or workflow that triggered it.
• Add expected vs actual behavior.

Next step
The accepted feature is security-sensitive and spans a new native target, pairing UX, Keychain handling, simulator proof, and a pre-release hardening dependency, so it needs sponsored human implementation rather than an autonomous repair PR.

Security
Needs attention: This security-sensitive feature has a defined server-side boundary, but its native client must preserve that boundary and the linked device-token hardening remains necessary before broad shipment.

Review details

Best possible solution:

Land a fresh, focused iOS implementation on current main that uses the existing pairing API only for read-only status views, includes the required redacted simulator/device proof, and completes the linked device-token hardening before broad availability.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is an accepted feature implementation request, not a report of broken existing behavior. The current-main and discussion evidence establish that the backend prerequisite exists while the native client does not.

Is this the best way to solve the issue?

Yes: the accepted narrow coordinator-only companion is the best path because it reuses the merged read-only pairing boundary instead of adding direct provider credentials, lifecycle actions, or a persistent in-app portal session.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The companion must preserve the server’s strict origin, distinct-device-principal, read-only, and redaction boundaries; a native client must not turn its device token into portal, provider, or lease-mutation authority.
• Before broad release, resolve or explicitly accept the credential-retention and membership-check behavior tracked in Device tokens: reduce OAuth credential retention and membership-check amplification #1200.

Codex review notes: model internal, reasoning high; reviewed against e31157d65ba5.

Label changes

Label changes:

• add clawsweeper:needs-security-review: Current issue advisory state selects this label.
• remove clawsweeper:needs-product-decision: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is an accepted but bounded new client surface whose implementation can proceed deliberately behind the existing coordinator contract.
• impact:security: The request depends on pairing grants, revocable device tokens, trusted-origin checks, Keychain storage, and fail-closed revocation.
• impact:auth-provider: The mobile flow authenticates through a distinct coordinator device principal and must not inherit portal or provider authority.

Evidence reviewed

Security concerns:

• [medium] Resolve device-token hardening before broad availability
  The linked follow-up identifies long-lived sealed OAuth retention and uncached membership revalidation in the pairing backend; the iOS release plan should not treat the merged prerequisite as the final security posture.
  Confidence: 0.96

What I checked:

• Accepted remaining scope: The July 2 decision accepts a narrow first-party iOS companion with coordinator pairing, device-token Keychain storage, system-browser portal handling, and read-only lease/status access; it explicitly excludes direct provider calls and mutation routes.
• Merged prerequisite, not the app: Merged PR 1199 implemented the server-side device-pairing slice and explicitly states that it implements only the server-side portion of this issue; the July 28 follow-up confirms the native companion remains outstanding. (docs/features/device-pairing.md, e1e5d143ef1f)
• Current-main product boundary: VISION.md: Current main documents Crabbox as a coordinator-backed remote-execution control plane and requires narrow, testable credential boundaries plus proof at the real user boundary; that supports the accepted coordinator-only mobile slice rather than the previously broad direct-provider client. (VISION.md:27, e31157d65ba5)
• Outstanding security follow-up: The linked open follow-up tracks retained OAuth credentials and per-request membership revalidation in device-token records, and its discussion states that it should be addressed before the iOS client ships broadly.

Likely related people:

• steipete: Authored the accepted v1 contract, merged the server-side device-pairing implementation, and linked the remaining security hardening work. (role: accepted-scope author and recent coordinator-auth contributor; confidence: high; commits: e1e5d143ef1f; files: docs/features/device-pairing.md, VISION.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Maintainer decision: first-party mobile is in scope, but only as a narrow read-only coordinator companion for v1.

Accepted v1 contract:

• Native SwiftUI shell with a small testable Swift package for URL, policy, auth state, and response models.
• One configured HTTPS coordinator origin; loopback may remain available for development builds only.
• Device pairing through a coordinator-hosted browser flow. The one-time pairing grant is short-lived, single-use, owner-bound, and exchanged for a revocable device token stored in Keychain.
• Device tokens may list the signed-in owner's visible leases and read lease/status details only.
• Portal pages open in the system browser. The app does not own a persistent WebView cookie jar.
• No provider API keys, direct provider calls, run/create/stop/release mutations, admin actions, marketplace/payment, LLM features, or Android surface in v1.

Security contract before UI expansion:

• Exact trusted-origin validation for pairing, token exchange, and API requests; no cross-origin credential redirects.
• Device tokens have a distinct audience and read-only scope, are bound to the verified coordinator owner, are individually revocable, and never inherit portal/admin authority.
• Pairing codes and device tokens stay out of argv, logs, analytics, crash text, URLs after exchange, repository config, and app screenshots.
• Revocation and owner/share changes fail closed on the next request; expired or replayed pairing grants cannot mint a token.

CI/proof contract:

• Swift package tests for origin policy, pairing state, token redaction, response decoding, and scope enforcement.
• Unsigned iOS simulator build on the accepted Xcode version.
• Required simulator proof: pair, list/status, revoke, then demonstrate denied access; also prove wrong-origin, expired-code, replayed-code, and destructive-route rejection.
• Fresh implementation PR from current main; do not revive the broad exploratory branch.

This issue remains open as the accepted implementation contract. Scope expansion needs a separate decision after the read-only slice ships.