E2EE onboarding: --e2ee decides at first connect, snapshot export for handover

.github/workflows/tests.yml

@@ -251,8 +251,10 @@ jobs:
         if: needs.changes.outputs.docs_only != 'true'
         run: |
           go install filippo.io/age/cmd/age@v1.3.1
+          go install filippo.io/age/cmd/age-keygen@v1.3.1
           npm config set prefix "$HOME/.npm-global"
           npm install -g bats
+          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
           echo "$HOME/.npm-global/bin" >> "$GITHUB_PATH"
 
       - name: Run age-v1 shared vectors
@@ -264,6 +266,13 @@ jobs:
           AGMSG_AGE_BIN="$age_bin" bats --print-output-on-failure tests/test_jsonl_remote_sync.bats
           AGE_BIN="$age_bin" node docs/spec/vectors/verify-age-v1-vectors.mjs
 
+      - name: Run encrypted onboarding CLI roundtrip
+        if: needs.changes.outputs.docs_only != 'true'
+        run: |
+          command -v age >/dev/null
+          command -v age-keygen >/dev/null
+          bats --print-output-on-failure --filter 'remote unlock:' tests/test_remote.bats
+
   # Continuously verify that the storage contract is backend-portable: run the
   # SAME driver-agnostic contract suite against the jsonl driver (the sqlite run
   # is covered by the `bats` job above). This catches silent rot in jsonl as the

SKILL.md

@@ -174,9 +174,11 @@ Do NOT manually edit config files. Always use join.sh. If the name was recently
 Remote setup is no-auth. Do not ask for a token or create one.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only
+   when the user explicitly requests end-to-end encryption. The choice is
+   fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the
    actual endpoint and team substituted:
    `bash ~/.agents/skills/agmsg/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
@@ -189,6 +191,18 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of
+   `--identity <file>` or `--identity-stdin`, and optional
+   `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never
+   infer or auto-confirm it. Raw identity material is a permanent secret; when
+   `--identity-stdin` is needed, tell the user to run the command in their own
+   terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine
+   PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh status [<team>] [--json]`

docs/remote-setup.md

@@ -3,6 +3,8 @@
 This walkthrough connects an existing team on machine A to the reference
 server, then pulls it into a normal agmsg install on machine B. Your local
 agents handle the client commands. This setup uses plaintext sync.
+For encrypted sync, read
+[Extra: end-to-end encryption](#extra-end-to-end-encryption).
 
 ## Requirements
 
@@ -82,6 +84,37 @@ The history should contain:
 <from> → <to>: hello from machine A
 ```
 
+## Extra: end-to-end encryption
+
+The remote team's encryption choice is fixed by its first connect and cannot
+be changed later. If you need an encrypted team, connect it with `--e2ee`:
+
+```sh
+bash ~/.agents/skills/agmsg/scripts/remote.sh connect \
+  --endpoint https://<server-url> \
+  --e2ee \
+  <team>
+```
+
+If the team has no key yet, connect creates one and prints the mandatory backup
+notice. It also shows how to export the compact public epoch snapshot. Transfer
+that snapshot and the private key to machine B through a separate trusted
+channel. Machine B still imports the key explicitly and live-confirms the
+displayed snapshot digest; the message server never distributes key material.
+After `pull` reports that the team is locked, machine B runs one command with
+the handed files and the digest verified over that separate live channel:
+
+```sh
+bash ~/.agents/skills/agmsg/scripts/remote.sh unlock <team> \
+  --snapshot <snapshot-file> \
+  --identity <identity-file> \
+  --confirm-digest <verified-sha256>
+```
+
+`unlock` imports the identity, records the trust anchor, reprocesses quarantined
+envelopes, and starts the encrypted sync engine. It is safe to repeat with the
+same confirmed files.
+
 ## Reference
 
 ### Install on machine B

scripts/drivers/types/antigravity/template.md

@@ -142,9 +142,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -153,6 +153,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/claude-code/template.md

@@ -222,9 +222,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -233,6 +233,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/codex/template.md

@@ -170,9 +170,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -181,6 +181,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/copilot/template.md

@@ -142,9 +142,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -153,6 +153,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/cursor/template.md

@@ -145,9 +145,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -156,6 +156,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/gemini/template.md

@@ -142,9 +142,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -153,6 +153,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`

scripts/drivers/types/grok-build/template.md

@@ -173,9 +173,9 @@ If argument is "reset":
 2. Tell the user the result.
 
 If argument starts with "remote connect":
-1. Parse the required `--endpoint <url>` and `<team>`.
-2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> <team>`
-3. Show the output to the user. No token or credential is required.
+1. Parse the required `--endpoint <url>` and `<team>`, plus optional `--e2ee`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh connect --endpoint <url> [--e2ee] <team>`
+3. Show the output to the user. Plain sync is the default; pass `--e2ee` only when the user explicitly requests end-to-end encryption. The choice is fixed by the first connect.
 4. End by showing this copy-paste command for the other machine, with the actual endpoint and team substituted: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <actual-url> <actual-team>`
 
 If argument starts with "remote pull":
@@ -184,6 +184,12 @@ If argument starts with "remote pull":
 3. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh pull --endpoint <url> [--team-id <uuid>] <team>`
 4. Show the output to the user.
 
+If argument starts with "remote unlock":
+1. Parse `<team>`, required `--snapshot <file>`, exactly one of `--identity <file>` or `--identity-stdin`, and optional `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --snapshot <file> (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. Raw identity material is a permanent secret; when `--identity-stdin` is needed, tell the user to run the command in their own terminal rather than asking them to paste the identity into agent chat.
+4. Show the complete result, including the imported-envelope count and engine PID.
+
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
 2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh status [<team>] [--json]`