agmsg-cloud 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/src/index.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { cmdWhoami } from './commands/whoami.js';
 import { loadConfig, resolveScriptsDir } from './config.js';
 import { cmdApprove } from './commands/approve.js';
 import { cmdConnect, cmdConnectPreflight } from './commands/connect.js';
@@ -36,6 +37,9 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
                                team this machine's store reports; name one to back up
                                only that team
   recovery restore <team>      (on any approved machine) open the backup and unlock <team>
+  whoami                       which of this account's machines this one is —
+                               its name, its organization, and the prefix the
+                               console shows beside it
   version                      the version of this CLI (also --version, -v)
                                the OSS scripts it drives are reported by
                                \`connect --preflight\`, which is a separate answer
@@ -54,6 +58,9 @@ environment variable for it.
 Environment (for CI and headless runs; \`login\` is the normal path):
   AGMSG_CLOUD_ENDPOINT   base URL of the hosted edge
   AGMSG_CLOUD_SECRET     this machine's capability secret
+  AGMSG_SCRIPTS_DIR      the agmsg install to drive
+                         (default: ~/.agents/skills/agmsg/scripts)
+                         \`connect --preflight\` prints the one it resolved
 
 Both or neither: a stored secret is only ever sent to the endpoint it was
 minted for, so one of these without the other is refused rather than mixed
@@ -100,6 +107,13 @@ async function main(argv) {
             process.stdout.write(`agmsg-cloud/${packageVersion()}\n`);
             return;
         }
+        // Beside `version` for the same reason it sits there: both answer a
+        // question about this machine and neither reaches the network, so both
+        // still work at the moment something else has refused.
+        case 'whoami': {
+            cmdWhoami();
+            return;
+        }
         case 'login': {
             // No endpoint means the official deployment. The flag stays for
             // self-hosted and development stacks; either way the destination is
@@ -144,7 +158,13 @@ async function main(argv) {
             const label = rest[0];
             if (!label)
                 throw new Error('usage: agmsg-cloud request <label>');
-            return cmdRequest(loadConfig(), { label });
+            // The outcome is dropped here on purpose: this is the whole command, and
+            // the exit code `request` set is what the shell reads. It is returned for
+            // the callers that run it as a STEP and have to decide whether to carry
+            // on — `sync` did not, which is how a failed enrollment ended in a
+            // message about a missing team.
+            await cmdRequest(loadConfig(), { label });
+            return;
         }
         case 'sync': {
             // The whole second-machine path. `request`, `fetch` and `pull` remain as
@@ -223,9 +243,17 @@ async function main(argv) {
             // to add that one on its own. `restore` still requires one — it unlocks a
             // specific team on this machine.
             //
-            // The excuse rides inside the slot, so it cannot apply to anything else.
+            // `restore`, written out. It is the only value `sub` can hold here — the
+            // branch tests for it — so the interpolation was indirection that printed
+            // a constant, and it carried a `printed-commands:` exemption to say so.
+            //
+            // That exemption was the last one in this file, and #201 is about what it
+            // rested on. Measured: nothing. The guard never reached this line, because
+            // a command introduced by `usage: ` opened no command extent, so the
+            // comment sat over a slot no rule was applied to. Both the comment and the
+            // slot are gone, and the line is now inside the guard's scope.
             if (sub === 'restore' && !team) {
-                throw new Error(`usage: agmsg-cloud recovery ${ /* printed-commands: a subcommand name this file chooses, narrowed to 'setup' | 'restore' two lines up — not a value anyone supplies, and quoting it would print `recovery 'setup'` */sub} <team>`);
+                throw new Error('usage: agmsg-cloud recovery restore <team>');
             }
             const config = loadConfig();
             return sub === 'setup'

package/dist/src/machine-id.js

@@ -0,0 +1,44 @@
+// Which of an account's machines THIS one is.
+//
+// The console lists an org's machines with a `token_prefix` column, so two
+// machines called `mbp2024` are two visibly different rows. Nothing on the
+// machine printed the matching value, so the distinction could be seen and not
+// resolved — the one person who knows which laptop they are sitting at had
+// nothing to compare against (#199). The revoke dialog names the prefix too
+// (#198), which makes that gap the difference between "these are two rows" and
+// "this one is mine".
+//
+// NOT A SECRET, and worth stating because it is carved out of one. The mint is
+// `agsy_<8 hex>_<43 base64url>` (app/src/edge/capability.ts) and the server
+// stores `agsy_<8 hex>` as the column the console shows to any org member. The
+// capability is the segment AFTER it, and it is what never leaves this file's
+// caller.
+/**
+ * The shape the server mints (app/src/edge/capability.ts): `agsy_<8 hex>_<43
+ * base64url>`, with the leading two segments captured.
+ *
+ * ONE definition, exported, because two callers need the same answer for
+ * different reasons: `login` refuses to STORE a secret that does not match, and
+ * `machinePrefix` refuses to READ a prefix out of one that does not. A second
+ * copy would let those drift — updating the mint in one place would leave the
+ * other silently answering about a format that no longer exists, and the
+ * failure would be a prefix that stops resolving rather than an error
+ * (raised in review).
+ */
+export const SECRET_RE = /^(agsy_[a-f0-9]{8})_[A-Za-z0-9_-]{43}$/;
+/**
+ * The prefix the console shows for this machine, or null if the stored secret
+ * is not the shape this version knows.
+ *
+ * Derived by MATCHING the whole shape rather than by cutting at a fixed length
+ * or at the first underscore. A slice would happily return the first 13
+ * characters of something that is not a capability at all — including, if the
+ * format ever changes, thirteen characters of live secret. It matches against
+ * the SAME exported pattern `login` uses to refuse storing a wrong shape —
+ * one definition with two callers, rather than two copies a comment claims
+ * are equal.
+ */
+export function machinePrefix(secret) {
+    const m = SECRET_RE.exec(secret);
+    return m ? m[1] : null;
+}

package/dist/src/oss.js

@@ -249,11 +249,25 @@ export async function unlockAuthenticatedBundle(scriptsDir, team, bundle) {
     await run('bash', [join(scriptsDir, 'remote.sh'), 'unlock', team, '--authenticated-bundle-stdin'], bundle);
 }
 // OSS `remote.sh unlock <team> --bundle <file> [--confirm-digest <digest>]`.
+//
+// RETURNS what the script said, rather than discarding it.
+//
+// `remote.sh unlock` does not print optimistically: it waits for the sync
+// engine to report ready, checks the recorded pidfile matches the process it
+// started, checks that process is alive, and exits non-zero otherwise. Only
+// then does it print `Unlocked '<team>': imported N envelope(s); engine
+// running (pid N).`
+//
+// That sentence is verified against a live pid, and it names the object. The
+// caller used to throw it away and print its own summary instead, which named
+// nothing — so an operator watching a successful join saw "unlocked" with no
+// way to tell WHICH thing had been unlocked, four lines above a remedy telling
+// them to unlock something (#147).
 export async function unlockBundle(scriptsDir, team, bundleFile, confirmDigest) {
     const args = [join(scriptsDir, 'remote.sh'), 'unlock', team, '--bundle', bundleFile];
     if (confirmDigest)
         args.push('--confirm-digest', confirmDigest);
-    await run('bash', args);
+    return (await run('bash', args)).toString();
 }
 // The canonical age snapshot, exported locally, and its digest (§3.2, §3.2.1).
 //

package/dist/src/preflight.js

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import { defaultScriptsDir, hasCredential, scriptsDirChoice } from './config.js';
 import { join } from 'node:path';
 import { platform } from 'node:process';
 // What `connect` needs before it starts, checked all at once.
@@ -150,10 +151,41 @@ function toolsFor(scripts) {
         python3: scripts.includes('remote.sh'),
     };
 }
-export function preflight(scriptsDir, needs) {
+export function preflight(scriptsDir, needs, env = process.env, 
+/**
+ * The home directory the default install would be under.
+ *
+ * Only ever passed by a check that needs to put a second install somewhere it
+ * owns. It is a parameter rather than `env.HOME` because this CLI runs on
+ * Windows too, where a POSIX-compatible shell sets `HOME` to a path
+ * `homedir()` does not return — reading it would have moved the default
+ * install for every Git Bash user in exchange for a testable line.
+ */
+home) {
     const { command, scripts } = needs;
     const requireConnect = needs.requireConnect ?? false;
     const requirements = [];
+    // BEING SIGNED IN IS A PREREQUISITE, so it is one of the things checked.
+    //
+    // It was not, and the result was a check that said "Everything connect needs
+    // is here" immediately before connect stopped for a missing sign-in (#222).
+    // A checklist that omits a requirement does not merely fail to help — it
+    // states that the requirement is met.
+    //
+    // Listed first because it is the one whose fix is a different command
+    // entirely, and because the others are about this machine's install while
+    // this one is about this machine's account.
+    requirements.push({
+        name: 'signed in',
+        // The resolver `loadConfig` uses, not a second opinion about the same
+        // question. `readCredential` alone reported a headless machine with
+        // AGMSG_CLOUD_ENDPOINT + AGMSG_CLOUD_SECRET as signed out — a checklist
+        // refusing a machine that CAN run the command, which is the defect this
+        // requirement exists to fix, facing the other way (raised in review).
+        ok: hasCredential(env),
+        why: `${command} talks to the hosted service as this machine, and this machine has no credential yet.`,
+        install: ['Sign in:             agmsg-cloud login'],
+    });
     // The scripts come first: without them nothing else matters, and the fix is
     // a different kind of thing (install agmsg, or point AGMSG_SCRIPTS_DIR at it)
     // than installing a binary.
@@ -205,9 +237,45 @@ export function preflight(scriptsDir, needs) {
         requirements,
         ok: requirements.every((r) => r.ok),
         command,
+        scriptsDir,
         agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
+        scriptsDirFrom: provenance(env, home),
+        otherInstalls: otherInstalls(scriptsDir, env, home),
     };
 }
+/**
+ * The install that exists at the location this command is NOT using.
+ *
+ * Only ever one, and only when `AGMSG_SCRIPTS_DIR` points somewhere other than
+ * the default: those are the two places `resolveScriptsDir` can name, so they
+ * are the two places worth reporting. `version.sh` is the marker rather than
+ * the directory itself — an empty `~/.agents/skills/agmsg/scripts` is not a
+ * second install, and calling it one would send someone to look at nothing.
+ */
+/**
+ * Which of the three states the resolution is in.
+ *
+ * Three, not two: the variable can be set AND point at the default, which is
+ * what someone has on the way to undoing an override. Collapsing it into "env"
+ * makes the output say "not the default location" about the default location.
+ */
+function provenance(env, home) {
+    const choice = scriptsDirChoice(env);
+    if (choice.from === 'default')
+        return 'default';
+    return choice.dir === defaultScriptsDir(home) ? 'env-at-default' : 'env';
+}
+function otherInstalls(scriptsDir, env, home) {
+    // Through the resolver's own accessor, so the two can never disagree about
+    // where "the default" is — a disagreement here would report the wrong
+    // directory as the one not in use.
+    const fallback = defaultScriptsDir(home);
+    if (scriptsDir === fallback)
+        return [];
+    if (!env.AGMSG_SCRIPTS_DIR)
+        return [];
+    return existsSync(join(fallback, 'version.sh')) ? [fallback] : [];
+}
 // The refusal in front of every command that shells out: one place decides how
 // a missing prerequisite reads, so it reads the same whichever command found
 // it.
@@ -230,6 +298,48 @@ export function formatPreflight(result) {
     for (const r of result.requirements) {
         lines.push(`  ${r.ok ? '[x]' : '[ ]'} ${r.name}`);
     }
+    // THE RESOLVED DIRECTORY, IN FULL, ON ITS OWN LINE.
+    //
+    // It used to appear only inside a requirement's name — `agmsg with remote
+    // sync (in /very/long/path)` — where the walk's terminal cut it off. The
+    // operator could not see WHICH install had been checked, which is exactly
+    // the disagreement they were trying to diagnose (#222). A path is not a
+    // decoration on a label; it is the answer to "which one did you look at".
+    lines.push('');
+    lines.push(`  scripts directory:       ${result.scriptsDir}`);
+    // WHAT PUT IT THERE, when something did.
+    //
+    // The hint below is advice to redirect the install. Printed while
+    // AGMSG_SCRIPTS_DIR is already set, it invites the reader to do the thing
+    // that is currently confusing them — "you could redirect this" when the truth
+    // is "this is redirected". So the two are alternatives, not a pair.
+    //
+    // Nothing extra when the default is in force: "this is the default" on every
+    // ordinary run is noise, and the sentence is only missing when something
+    // non-default is deciding.
+    if (result.scriptsDirFrom === 'env') {
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, not the default location.`);
+    }
+    else if (result.scriptsDirFrom === 'env-at-default') {
+        // The variable is set AND points at the default. Saying "not the default
+        // location" here would be false, and it is the state someone reaches while
+        // trying to undo an override — the one moment the sentence has to be exact.
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, which points at the default location.`);
+    }
+    else {
+        lines.push(`  set AGMSG_SCRIPTS_DIR to check a different install.`);
+    }
+    // NAMES THE OTHER ONE, and says which of the two is in force.
+    //
+    // Without this the reader has to decide, and an agent that finds two installs
+    // stops and asks — the incident four lines of the handed-over prompt exist to
+    // prevent (issue 279). The answer is not a preference to be settled; it is
+    // already settled by the resolver, and this is it being said out loud.
+    for (const other of result.otherInstalls) {
+        lines.push('');
+        lines.push(`  another install is here:  ${other}`);
+        lines.push(`  it is NOT the one in use — AGMSG_SCRIPTS_DIR decides, and it points above.`);
+    }
     if (result.agmsgVersion !== null) {
         // Named as what it is. Calling it "agmsg 1.1.11" would invite the reader to
         // compare it with a release number, which is the thing it cannot be
@@ -241,6 +351,15 @@ export function formatPreflight(result) {
     if (missing.length === 0) {
         lines.push('');
         lines.push(`Everything ${result.command} needs is here.`);
+        // SAYS THAT THIS IS THE CHECK.
+        //
+        // An agent told "make sure the prerequisites are met" checks them again
+        // unless something says not to — it has no way to know this output was the
+        // check rather than a summary of one. The prompt carries a sentence for
+        // exactly that ("do not check for tools yourself"), which is a property
+        // this output should have rather than a warning the reader must be given
+        // separately (issue 279).
+        lines.push(`This was the check. Nothing else needs testing before you run it.`);
         return `${lines.join('\n')}\n`;
     }
     for (const r of missing) {

package/dist/src/recovery-key.js

@@ -281,20 +281,35 @@ export function promptRecoveryKey(prompt) {
 // can then be re-derived from material this machine holds. It does not exist
 // yet, so the caller shows first and says so if the backup then fails.
 //
-// The command it prints is the REAL one, built from the team this run was
-// given and quoted through `shellArg` (raised in review). It used to read
-// `agmsg-cloud recovery setup` with no argument, which the dispatch refuses —
-// so the one line telling someone what to do next was a line that could only
-// produce a usage error. A `<team>` placeholder would have the same defect in
-// a politer form: what is printed here is meant to be pasted, so it has to be
-// the command that runs, for the team this failure happened on, including
-// when that name is not one shell word.
+// The command it prints is the REAL one — whatever `setupCommand` builds for
+// the team this run was given, or for no team when it was given none. What is
+// printed here is meant to be PASTED, so it has to be a command that runs: a
+// `<team>` placeholder is not, and a name that is not one shell word has to
+// arrive quoted (raised in review).
+//
+// This paragraph used to add that the no-argument form "the dispatch refuses",
+// and that printing it could only produce a usage error. That was true when the
+// team was required. It stopped being true when the argument became optional,
+// and the sentence sat directly above the derivation that says the opposite
+// (#182 review). Both halves are still printable and both still run; which one
+// appears is decided by the caller having a team in hand, not by one of them
+// being invalid.
 // The command to re-run. The quoting sits ON the interpolating line, which is
 // what the printed-command checker reads — a ternary hid it, and so did binding
 // the result to a variable first. Both were still quoted; neither was visible.
 // The checker is right to demand the stricter form: what it can see is what
 // survives the next edit.
-function setupCommand(team) {
+/**
+ * How this tool names the command that creates a vault and backs teams up.
+ *
+ * One derivation, because the argument convention has already moved once: the
+ * team used to be required and is now optional, and the no-argument form is the
+ * ordinary one — it covers every team this machine reports rather than the one
+ * that happened to be in hand. Every place that prints this remedy asks here,
+ * so the next change to the convention moves one line rather than being grepped
+ * for (#181).
+ */
+export function setupCommand(team) {
     if (team === undefined)
         return 'agmsg-cloud recovery setup';
     return `agmsg-cloud recovery setup ${shellArg(team)}`;

package/dist/src/slot-advice.js

@@ -1,3 +1,4 @@
+import { setupCommand } from './recovery-key.js';
 import { shellArg } from './shell-arg.js';
 /**
  * Explain a slot that did not open, given the command that will now ask for the
@@ -65,6 +66,90 @@ export function adviseOnSlot(result, ctx) {
             };
     }
 }
+/**
+ * Explain a slot that did not open, given a command that will NOT ask for the
+ * recovery key — `connect`, which files the team's key into the vault silently
+ * or not at all.
+ *
+ * A second mapping rather than a second wording of the first: the sentences
+ * above all end in "the recovery key is typed and this run continues", and
+ * every one of them is false here. Nothing continues; the team is not in the
+ * vault, and what the person needs is the route that puts it there.
+ *
+ * The two live in one file, side by side, because they are one judgement read
+ * twice. `OpenResult['reason']` is a union and both switches are exhaustive, so
+ * a fifth reason cannot be answered in one of them and forgotten in the other —
+ * it fails to compile until both have looked at it.
+ *
+ * The `no-store` branch is why this exists at all. The prompting caller can say
+ * "the key is needed for each backup" and be done; here, the honest sentence is
+ * that this machine will never file silently, and a remedy that said "run
+ * `recovery setup` once and this stops happening" would be a route that does
+ * not exist on Windows or Linux.
+ */
+export function adviseOnSlotForSilentFiling(result, ctx) {
+    if (result.ok)
+        return { tone: 'silent', lines: [] };
+    // NAMED, and the argument is the point rather than a detail.
+    //
+    // `recovery setup` takes the team optionally now, and the no-argument form is
+    // the one its own documentation calls ordinary — which is why this printed it
+    // at first. But the broad form's success depends on every OTHER team the
+    // machine reports: one pass, no per-team isolation, so a `key.sh handoff`
+    // that fails for an unrelated team throws out of the loop and nothing is
+    // written. And if `remote.sh status --json` comes back short (agmsg#650) the
+    // target list can be empty, which refuses outright.
+    //
+    // Either way the person is sent to a command that can fail for a reason that
+    // has nothing to do with the team they just connected — and this is the one
+    // route they are given. Naming the team makes the remedy reach exactly the
+    // thing the sentence above it is about (raised in review).
+    const setup = `\`${setupCommand(ctx.team)}\``;
+    switch (result.reason) {
+        case 'no-slot':
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no key slot for this vault, so the team was not backed up.',
+                    `Run ${setup} and type the recovery key once; after that this machine`,
+                    'files new teams itself.',
+                ],
+            };
+        case 'no-store':
+            // The one that must not promise a fix. There is no secure store to keep a
+            // slot in, so every future `connect` on this machine lands here too.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has no secure store, so it cannot back up a team without the recovery',
+                    `key: the team was not backed up. Run ${setup} to back it up now.`,
+                    'This machine will need the key each time; a machine with a secure store will not.',
+                ],
+            };
+        case 'store-locked':
+            // Order matters here and only here: running setup against a locked store
+            // backs the team up but keeps no slot, so the next connect asks again.
+            return {
+                tone: 'note',
+                lines: [
+                    'this machine has a secure store but it refused: ' + result.detail,
+                    `The team was not backed up. Unlock the store, then run ${setup} —`,
+                    'in that order, so a key slot is kept and later teams are filed without asking.',
+                ],
+            };
+        case 'unusable':
+            return {
+                tone: 'warning',
+                lines: [
+                    'this machine has a key slot for this vault and its contents did not hold up: ' +
+                        result.detail,
+                    `The team was not backed up. Run ${setup}, which asks for the recovery`,
+                    'key and replaces the slot. Until then this team exists only on the machines',
+                    'holding it.',
+                ],
+            };
+    }
+}
 /** Render advice for a terminal. Empty string when there is nothing to say. */
 export function renderSlotAdvice(advice) {
     if (advice.lines.length === 0)

package/dist/src/vault-container.js

@@ -87,6 +87,45 @@ export function upsertTeam(container, entry) {
     const teams = [...others, entry].sort((a, b) => (identityOf(a) < identityOf(b) ? -1 : 1));
     return { format: CONTAINER_FORMAT, version: CONTAINER_VERSION, teams };
 }
+/**
+ * The same two key epochs, however they are ordered.
+ *
+ * A set comparison, not a sequence one: the epochs come out of a bundle the OSS
+ * side produced, and nothing promises the order is stable between two runs.
+ * Comparing them in order would report a change on a re-ordering and append a
+ * version identical to the one before it.
+ */
+export function sameEpochs(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((v, i) => v === right[i]);
+}
+/**
+ * Put one team into the container, unless its epochs are already the ones in
+ * there.
+ *
+ * The `written` half is the point. `recovery setup` documents itself as
+ * idempotent — "a run where no team's epochs have moved writes nothing and
+ * leaves the revision where it was" — and that promise belongs to the container,
+ * not to the command that happened to make it first. `connect` files a team the
+ * moment it is created and is re-runnable, so without this a second `connect`
+ * on a team already in the vault appends a version identical to the one before
+ * it, and the revision history stops meaning "something changed here".
+ *
+ * Kept beside `upsertTeam` rather than in either caller, because two copies of
+ * "has this actually moved" that drifted would disagree about whether a write
+ * was needed — and the one that said yes would silently win.
+ */
+export function upsertTeamIfMoved(container, entry) {
+    const key = identityOf(entry);
+    const already = container.teams.find((t) => identityOf(t) === key);
+    if (already && sameEpochs(already.key_ids, entry.key_ids)) {
+        return { container, written: false };
+    }
+    return { container: upsertTeam(container, entry), written: true };
+}
 export function serializeContainer(container) {
     return Buffer.from(JSON.stringify(container), 'utf8');
 }

package/dist/src/vault-filing.js

@@ -0,0 +1,62 @@
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { openDeviceSlot } from './device-slot.js';
+import { keyHandoff, remoteBinding } from './oss.js';
+import { parseContainer, serializeContainer, upsertTeamIfMoved } from './vault-container.js';
+import { appendVaultVersionWithVdk, openVaultWithVdk, readAccountVault } from './vault-protocol.js';
+import { bundleKeyIds, slotAddress } from './commands/vault.js';
+/**
+ * File one team's handoff bundle into this account's vault, if that can be done
+ * silently.
+ *
+ * Fails closed in the sense that matters: it never invents a vault, never asks
+ * for a key, and never reports success for a write it did not make.
+ */
+export async function fileTeamInVaultSilently(config, client, team) {
+    const { identity, version } = await readAccountVault(client);
+    // No vault means there is no recovery key either — creating one here would
+    // mint a key and show it during a command nobody ran for that purpose.
+    if (!version)
+        return { filed: false, reason: 'no-vault' };
+    const opened = await openDeviceSlot(slotAddress(identity, version.vault_id, version.recovery_generation));
+    // Every way of not having a slot lands here, and none of them is an error:
+    // a machine that has never run `recovery setup`, a platform with no secure
+    // store, a locked keychain. The caller names the route instead.
+    if (!opened.ok)
+        return { filed: false, reason: 'no-slot', slot: opened };
+    const binding = await remoteBinding(config.scriptsDir, team);
+    const current = openVaultWithVdk(identity, version, opened.vdk);
+    const container = parseContainer(current.content);
+    const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-filing-'));
+    try {
+        const bundleFile = join(scratch, 'handoff.bundle');
+        await keyHandoff(config.scriptsDir, team, bundleFile);
+        const bundle = readFileSync(bundleFile);
+        // The same decision `recovery setup` makes, from the same function.
+        //
+        // `connect` is re-runnable — a second run on a team that is already
+        // connected continues to the registration rather than refusing — so
+        // without this it would append a version identical to the one before it
+        // every time. `recovery setup` documents itself as idempotent; a second
+        // writer that is not makes that sentence false about the account.
+        const { container: next, written } = upsertTeamIfMoved(container, {
+            server_instance_id: binding.serverInstanceId,
+            team_id: binding.teamId,
+            key_ids: bundleKeyIds(bundle),
+            bundle: bundle.toString('base64'),
+        });
+        if (!written) {
+            // Backed up, and this run is not what did it. Told apart from a write
+            // because the caller says "revision N" and there is no new N to say.
+            return { filed: true, wrote: false, revision: version.revision, teamCount: next.teams.length };
+        }
+        const result = await appendVaultVersionWithVdk(client, identity, version, opened.vdk, serializeContainer(next));
+        return { filed: true, wrote: true, revision: result.revision, teamCount: next.teams.length };
+    }
+    finally {
+        // The bundle is key material. Removed on every path this process controls,
+        // the same way the ceremony's snapshot is.
+        rmSync(scratch, { recursive: true, force: true });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.7",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,7 +33,8 @@
     "pretypecheck": "pnpm run build:deps",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsx scripts/check-printed-commands.ts && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
-    "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts"
+    "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
+    "verify:published": "tsx scripts/verify-published.ts"
   },
   "dependencies": {
     "@agmsg-cloud/sas-core": "workspace:*",