feat(key): one file to hand over — handoff bundles the chain and its identities

SKILL.md

@@ -192,16 +192,16 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--snapshot <file> ...] (--identity <file>|--identity-stdin) [--confirm-digest <sha256>]`
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/agmsg/scripts/remote.sh unlock <team> --bundle <file> --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.
+   infer or auto-confirm it. The bundle is permanent secret key material; tell
+   the user to transfer and handle it only through their own trusted channel,
+   never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine
    PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or
+   `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -226,6 +226,13 @@ If argument starts with "key show":
    agent mode. Tell the user to run it directly in their own terminal.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run:
+   `bash ~/.agents/skills/agmsg/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent
+   secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. Do not ask the user to paste the private identity into this chat, and do not
    run the command yourself. Tell the user to run this in their own terminal:

docs/remote-setup.md

@@ -97,23 +97,28 @@ bash ~/.agents/skills/agmsg/scripts/remote.sh connect \
 ```
 
 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:
+notice. On machine A, export one secret handoff bundle containing the confirmed
+snapshot chain and every epoch identity:
+
+```sh
+bash ~/.agents/skills/agmsg/scripts/key.sh handoff <team> --out <bundle-file>
+```
+
+Transfer that bundle to machine B through a separate trusted channel. The
+message server never distributes key material. Compare the displayed snapshot
+digest over a separate live channel. After `pull` reports that the team is
+locked, machine B runs:
 
 ```sh
 bash ~/.agents/skills/agmsg/scripts/remote.sh unlock <team> \
-  --snapshot <snapshot-file> [--snapshot <next-snapshot-file> ...] \
-  --identity <identity-file> \
+  --bundle <bundle-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.
+same confirmed bundle. The bundle contains private keys: keep it secret and
+delete the transferred copy when it is no longer needed.
 
 ## Reference
 

scripts/drivers/types/antigravity/template.md

@@ -154,10 +154,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -179,6 +180,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```

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

@@ -234,10 +234,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -259,6 +260,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```

scripts/drivers/types/codex/template.md

@@ -182,10 +182,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -207,6 +208,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```

scripts/drivers/types/copilot/template.md

@@ -154,10 +154,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -179,6 +180,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```

scripts/drivers/types/cursor/template.md

@@ -157,10 +157,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -182,6 +183,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```

scripts/drivers/types/gemini/template.md

@@ -154,10 +154,11 @@ If argument starts with "remote pull":
 4. Show the output to the user.
 
 If argument starts with "remote unlock":
-1. Parse `<team>`, one or more `--snapshot <file>` arguments in ascending revision order, 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> [--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.
+1. Parse `<team>`, `--bundle <file>`, and `--confirm-digest <sha256>`.
+2. Run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/remote.sh unlock <team> --bundle <file> --confirm-digest <sha256>`
+3. The snapshot digest must be compared over a separate live channel. Never infer or auto-confirm it. The bundle is permanent secret key material; tell the user to transfer and handle it only through their own trusted channel, never by pasting it into agent chat.
 4. Show the complete result, including the imported-envelope count and engine PID.
+5. The advanced form with repeatable `--snapshot` plus `--identity` or `--identity-stdin` remains available when explicitly requested.
 
 If argument starts with "remote status":
 1. Parse an optional `<team>` and `--json`.
@@ -179,6 +180,11 @@ If argument starts with "key show":
 3. `--reveal-secret` requires a real interactive terminal and is refused in agent mode — if the user wants to reveal a secret, tell them to run it themselves directly in their own terminal rather than through you.
 4. Show the output to the user.
 
+If argument starts with "key handoff" followed by a team name:
+1. Parse optional `--out <file>` and run: `bash ~/.agents/skills/__SKILL_NAME__/scripts/key.sh handoff <team> [--out <file>]`
+2. The output bundle contains every epoch identity and is itself permanent secret key material. Never read it into agent chat or display its contents.
+3. Show the bundle path, latest snapshot digest, and full secrecy warning.
+
 If argument starts with "key import" followed by a team name:
 1. **Do not ask the user to paste the private identity into this chat, and do not run this command yourself.** This identity is a permanent secret. Tell the user to run this directly in their own terminal:
    ```