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 August 1, 2026, 12:18 PM ET / 16:18 UTC.

Summary
Keep open: current main has the restricted coordinator pairing backend, but not the requested first-party SwiftUI iOS companion. The accepted v1 contract remains a security-sensitive, human-sponsored feature rather than a bounded autonomous repair.

Reproducibility: not applicable. this is an accepted feature request. Source inspection confirms the server-side read-only API exists, while the requested native iOS client does not.

Root-cause cluster
Relationship: canonical
Canonical: #778
Summary: This issue is the accepted client-side implementation contract. The merged pairing PR supplied its server prerequisite, while the earlier broad mobile branch was deliberately replaced by this narrower scope.

Members:

• fixed_by_candidate: feat(worker): add read-only device pairing #1199 - The merged PR provides the restricted pairing and read-only lease API required by the future companion, but it does not add the iOS client.
• superseded: feat: native SwiftUI Crabbox iOS app (crabbox.sh client + on-device/sandbox LLM + islo) #379 - The broad exploratory mobile branch was closed unmerged and the discussion explicitly replaced it with this read-only companion contract.
• adjacent_distinct: Device tokens: reduce OAuth credential retention and membership-check amplification #1200 - It tracked server-side device-token credential-retention and membership-check hardening rather than the native companion implementation.

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.
• Add expected vs actual behavior.

Next step
The feature has accepted scope but spans a new native target, protected credential handling, security proof, and iOS CI ownership, so it needs sponsored human implementation rather than an autonomous repair PR.

Security
Needs attention: No patch is under review, but any future implementation must preserve the coordinator’s deliberately narrow device-token security boundary.

Review details

Best possible solution:

Land a fresh, narrow iOS companion that uses only the documented pairing and lease-read APIs, stores its token in Keychain, and supplies redacted simulator proof for the accepted pairing, status, revocation, and rejection flows.

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

Not applicable: this is an accepted feature request. Source inspection confirms the server-side read-only API exists, while the requested native iOS client does not.

Is this the best way to solve the issue?

Yes: the approved read-only coordinator companion is the narrowest maintainable path because it avoids direct provider credentials and lifecycle authority on the device.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A new native client must preserve the documented trusted-origin, token-redaction, Keychain, pairing-reauthentication, and immediate revocation behavior rather than creating a parallel credential model.
• Current main lacks the iOS target and simulator/device evidence required to demonstrate pairing, status access, revoked-token denial, malformed-origin denial, expired/replayed-grant denial, and destructive-route rejection.

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

Label changes

Label justifications:

• P3: This is an accepted but non-urgent new companion surface, not a current remote-execution regression.
• impact:security: The feature adds a native client around device tokens, browser pairing, protected credential storage, origin validation, and revocation.
• impact:auth-provider: Device access depends on pairing grants, a distinct token audience and scope, and owner membership revalidation.

Evidence reviewed

Security concerns:

• [high] Preserve the device-token security model — docs/features/device-pairing.md:9
  The native app must use protected credential storage and only the documented read-only device routes; it must not add direct provider keys, persistent portal-cookie ownership, or lifecycle authority.
  Confidence: 0.96

What I checked:

• Accepted implementation contract: The issue discussion records the accepted v1 direction: a first-party native SwiftUI shell using a coordinator-hosted browser pairing flow, one configured HTTPS origin, a Keychain-stored revocable device token, and read-only lease/status access only.
• Current server-side security boundary: Current documentation defines a distinct crabbox-device principal limited to lease GET routes; device responses redact connection and provider-access data, never call providers, and never write coordinator state. (docs/features/device-pairing.md:9, 0171ae2ee19f)
• Existing enforcement and regression coverage: Current Worker tests prove device credentials receive 403 device_scope_forbidden for lifecycle, sharing, administrative, and authoritative-metadata requests. (worker/test/pairing.test.ts:354, 0171ae2ee19f)
• No requested iOS companion on current main: The checked-out Swift sources belong to the unrelated vmd virtual-machine package; there is no mobile/ directory, iOS app target, or companion SwiftUI source tree on current main. (vmd/Package.swift:1, 0171ae2ee19f)
• Pairing prerequisite provenance: The merged coordinator pairing feature is commit e1e5d143ef1fc169c2b075d76ae8b9d8a9b50675; current file history records the later device-token revalidation hardening in e31157d65ba5132861e258f9230153086622d8f6. (docs/features/device-pairing.md:58, e31157d65ba5)
• Release and main position: The latest declared release commit is v0.40.0 from July 19, 2026, while the pairing merge is dated July 28, 2026 and is contained in current main; the server prerequisite is newer than that release. (CHANGELOG.md:1, e1e5d143ef1f)

Likely related people:

• steipete: The accepted v1 contract is recorded under this handle, and local history attributes both the pairing merge and follow-up device-token revalidation hardening to Peter Steinberger. (role: introduced and recently hardened the coordinator pairing boundary; confidence: high; commits: e1e5d143ef1f, e31157d65ba5; files: worker/src/pairing.ts, worker/src/fleet.ts, worker/test/pairing.test.ts)

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.