Repository navigation
docs(cross-device-sync): add boss-link sync and remote control design - #1
Conversation
Research report and design for syncing one person's data across the the-boss-mobile and The Boss desktop apps and controlling any executor from any device: iroh transport, signed device roster, command envelopes, per-field LWW sync with a transactional outbox, canonical entity mapping, per-platform implementation plans, roadmap, and three rounds of adversarial review. The same docs/webrtc directory is mirrored in Prometheus-AGS/the-boss. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 38bd4e2dd1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| entries after that point. **`DeviceRevoked` entries are never invalidated:** any valid ADK-signed | ||
| `DeviceRevoked` found at or after the superseded position (including on a branch learned later from a peer | ||
| that was unreachable during recovery) is carried forward by the new admin as a new `DeviceRevoked`, and every | ||
| device applies it on sight even before it is carried forward. | ||
| - After `AdminReplaced`, nothing signed by the old ADK is accepted except `DeviceRevoked`. |
There was a problem hiding this comment.
When recovery is triggered because the old ADK was lost or compromised, these rules continue accepting every DeviceRevoked signed by that old key indefinitely. An attacker holding it can therefore sign fresh revocations after AdminReplaced—including revoking the replacement admin or all remaining devices—and every peer is required to apply them on sight. Preserve previously issued revocations using a bounded cutoff or entries committed before replacement, but reject new signatures from the old ADK.
Useful? React with 👍 / 👎.
| 5. `msg_id` not in the journal. The journal keeps entries for 24 h (≥ maximum lifetime + skew). A duplicate | ||
| returns the stored result. | ||
| 6. Grant and local policy permit the method. | ||
| 7. Step-up present and valid when required (high-risk approvals, `exec.shell`, `secrets`, `control.unlock`). | ||
| 8. For session-targeted methods, `home_epoch` matches the session's current epoch (§7.3). | ||
| 9. Hand the RPC to the host; journal the result. |
There was a problem hiding this comment.
For non-idempotent RPCs such as agent.messages.send, session creation, and jobs.run, a utility-process or app crash after the host commits the operation but before step 9 journals its result leaves msg_id absent from the journal. Retrying the envelope then passes the duplicate check and executes the operation again, contradicting the architecture's exactly-once guarantee. Persist an in-progress/idempotency record before handing the request to the host and provide a durable way to resolve recovery after an ambiguous host commit.
Useful? React with 👍 / 👎.
| - Bookkeeping: each app keeps `sync_field_state(entity_type, entity_id, field, hlc)` (or equivalent) so the | ||
| projector never overwrites a local field whose HLC is newer (for example a local edit not yet drained). |
There was a problem hiding this comment.
The stated bookkeeping cannot protect the cited undrained-edit case: the core assigns the edit's HLC only when it drains the outbox, while the same-transaction outbox schema stores only local_rev and the projector compares only sync_field_state.hlc. If an older remote projection arrives between the local commit and drain, it can overwrite the local database value before that value has an HLC in sync_field_state; depending on how changed_fields_json is materialized, the edit is then either lost or leaves the app database inconsistent with sync.db. The design needs to reserve/store the local HLC transactionally or explicitly defer projection for fields with pending local revisions.
Useful? React with 👍 / 👎.
| | JobRun (`id`, `schedule_id`, `executor_device`, `row_rev`, `type`, `status`, `scheduled_at`, `started_at`, `finished_at`, `output`, `error`) | R (executor) | `job` (read-only replicas of remote runs, `executable_here = false`) | `job` | | ||
| | Queue, attempt, idempotency, cancel flags, timeouts | — | local-only | local-only | |
There was a problem hiding this comment.
The proposed JobRun mapping cannot be inserted into the current mobile job table: src/backend/data/db/schemas/job.ts requires a non-null input value with no database default, but the canonical row omits input and declares unlisted columns local-only. Consequently every remote job-run projection either violates the constraint or invents an unspecified value. Add the required field to the canonical model or define a deterministic projection value for mobile replicas.
Useful? React with 👍 / 👎.
1 participant
Summary
docs/webrtc/: research report and design for boss-link, a shared Rust core that keeps one person's data in sync across The Boss desktop and the-boss-mobile and lets any device control executors (desktops / headless nodes) from anywhere.agent.*/configuration.*JSON-RPC methods carried in signed envelopes verified by the Rust core (roster, time, replay, grants, local policy, hardware step-up, home epoch).Prometheus-AGS/cherry-studio-appandPrometheus-AGS/the-bossso agents in either repo can implement their half against the other.Documentation only — no code changes.
Test plan
pnpm docs:check-linkspassesdiff -rq)🤖 Generated with Claude Code