agmsg-cloud 0.1.0-rc.3 → 0.1.0-rc.4

package/README.md

@@ -23,7 +23,9 @@ agmsg-cloud login                  sign this machine in
 agmsg-cloud connect <team>         put a team this machine runs onto the service
 agmsg-cloud sync <team>            (on a new machine) ask to join, and wait
 agmsg-cloud approve <team>         (on a machine that has the keys) answer that request
-agmsg-cloud recovery setup <team>  create the team's recovery key and back the keys up
+agmsg-cloud recovery setup         create the account's recovery key and back up every
+                                   active team this machine's store reports
+
 ```
 
 `sync` and `approve` are two halves of one ceremony: each screen shows eight

package/dist/src/api.js

@@ -21,6 +21,7 @@ const STATUSES = [
     'consumed',
     'expired',
     'failed',
+    'refused',
 ];
 // Ranges, not types.
 //
@@ -365,6 +366,22 @@ export class CourierClient {
             if (!isObject(d) || !isRecipient(d['devicePubkey']) || !isUuid(d['id'])) {
                 throw new CourierError(200, 'malformed_devices_response');
             }
+            // `thisMachine` DECIDES A REFUSAL, so it is checked like one.
+            //
+            // Absent or boolean, nothing else. `"true"`, `null` and `0` are all
+            // truthy-or-falsy in some reading, and any of them would make the
+            // pre-flight below treat a row as "not this machine" while ALSO treating
+            // the response as coming from a server that answers the question — so an
+            // ordinary rejoin would be refused locally, without a single request
+            // reaching the server that could have corrected it.
+            //
+            // Refused here rather than coerced: this value gates a decision no other
+            // check re-derives, and the pre-flight's own catch turns a malformed
+            // response into "go ahead and run the ceremony", which is the safe
+            // direction (raised in review).
+            if (d['thisMachine'] !== undefined && typeof d['thisMachine'] !== 'boolean') {
+                throw new CourierError(200, 'malformed_devices_response');
+            }
         }
         return out['devices'];
     }

package/dist/src/ceremony.js

@@ -30,7 +30,11 @@ export class CeremonyError extends Error {
 const PROGRESSION = ['requester_committed', 'both_committed', 'requester_opened', 'opened', 'consumed'];
 // Ends the ceremony without reaching the end. Not the same as 'consumed', which
 // is the end.
-const TERMINAL_FAILURE = ['expired', 'failed'];
+// 'refused' belongs here even though it costs no attempt: a waiter's question
+// is "can this still finish", and the answer is no. What it costs is a separate
+// question, answered by the ledger and by the server's counters — a waiter that
+// left it out would poll a dead request until it timed out.
+const TERMINAL_FAILURE = ['expired', 'failed', 'refused'];
 function rank(status) {
     return PROGRESSION.indexOf(status);
 }
@@ -137,9 +141,22 @@ export function renderSasBlock(sas, role) {
         // Only the approver is asked anything. Telling the joining machine's
         // operator to "answer no" pointed at a prompt that does not exist on their
         // side, one line above the sentence explaining that the approver decides.
-        role === 'approver'
-            ? '  If they differ at all, answer no. That is what this check is for.'
-            : '  The approver decides. If they confirm, this machine is added.',
+        //
+        // SAID HERE AND NOWHERE ELSE. `request` printed its own version of the
+        // requester's sentence straight after this block, so the screen read: who
+        // decides -> how to compare remotely -> who decides (#195). The block is
+        // the one place that knows which side it is rendering for, so it is the
+        // one place that says it.
+        //
+        // The wording is the LONGER of the two that existed, because it carried
+        // something this one did not: what a `no` means. Deduplicating by keeping
+        // the shorter line would have deleted that with it.
+        ...(role === 'approver'
+            ? ['  If they differ at all, answer no. That is what this check is for.']
+            : [
+                '  The approver decides. If they confirm, this machine is added and can',
+                '  fetch its bundle; if not, nothing is sent and this request is over.',
+            ]),
         '',
         // Addressed to the people it applies to, and to nobody else.
         //

package/dist/src/commands/fetch.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { CourierClient } from '../api.js';
 import { clearAuthenticatedDigest, readAuthenticatedDigests } from '../authenticated-digest.js';
 import { originOf } from '../credentials.js';
-import { decryptWithIdentity, publicKeyOf, unlockBundle, verifyHandoffDigest } from '../oss.js';
+import { decryptWithIdentity, localTeamLookup, publicKeyOf, unlockBundle, verifyHandoffDigest, } from '../oss.js';
 import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
 // (c, part 2) B fetches the sealed bundles addressed to its device, opens each
@@ -23,9 +23,51 @@ env = process.env) {
     // approval was recorded under, so a regenerated identity does not inherit
     // the previous one's ceremonies (raised in review).
     const devicePubkey = await publicKeyOf(idPath);
+    // ASKED BEFORE THE QUEUE IS REPORTED ON (#145).
+    //
+    // `fetchBlobs` is scoped to the DEVICE, not to the team, and the team name is
+    // not read until `unlock` at the far end — so an empty queue and a mistyped
+    // name produced the same sentence. Measured on one machine with one
+    // credential:
+    //
+    //   fetch walkfresh1        -> no pending bundles   (real team, empty queue)
+    //   fetch zzz-no-such-team  -> no pending bundles   (never existed)
+    //
+    // "no pending bundles" was true of the second and useless: someone waits for
+    // a bundle that will never arrive under that name. It is the same argument
+    // the `--confirm-digest` branch below already makes out loud — a thing
+    // silently ignored is how someone keeps believing they are the check.
+    //
+    // The queue is unchanged and so is every gate after it. What changes is that
+    // a name this machine does not have is refused BY NAME instead of answered.
+    // STOPS AT WHAT WAS OBSERVED, which is that the lookup did not succeed.
+    //
+    // It said "this machine has no team called X" — an assertion about absence,
+    // from a non-zero exit that has more than one cause: an unknown name, a
+    // config that could not be read, a store lock, the script failing to start.
+    // This repository has already MEASURED that the first two are
+    // indistinguishable from here — a corrupt team and an unconnected one give
+    // the same exit code and the same sentence (agmsg#650, found while reviewing
+    // #192). Naming a cause that was ruled indistinguishable, and then printing
+    // the store's own words underneath, does not undo the first line: the first
+    // line is what gets believed.
+    //
+    // So the two readings are given, and the store's words carry whichever it is
+    // (raised in review).
+    const lookup = await localTeamLookup(config.scriptsDir, args.team);
+    if (!lookup.known) {
+        throw new Error(`this machine could not confirm a team called ${JSON.stringify(args.team)}, so there is\n` +
+            '  nothing here it can unlock.\n' +
+            (lookup.said ? `\n  The store said: ${lookup.said}\n` : '') +
+            '\n  That reads two ways and this machine cannot tell them apart: there may be no\n' +
+            '  team by that name here, or its state could not be read.\n' +
+            '\n  If the name is right, `agmsg-cloud pull` is what puts a team on a machine, and\n' +
+            '  `agmsg-cloud sync` does that and this in one go.');
+    }
     const client = new CourierClient(config);
     const blobs = await client.fetchBlobs();
     if (blobs.length === 0) {
+        // Now this says something: the team IS here, and nothing is waiting.
         process.stdout.write('no pending bundles\n');
         return;
     }

package/dist/src/commands/login.js

@@ -1,6 +1,6 @@
 import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../browser.js';
 import { isOrgAddress, originOf, readCredential, writeCredential } from '../credentials.js';
-import { settleMachineName } from '../machine-name.js';
+import { settleMachineName, validateMachineName } from '../machine-name.js';
 // `login` — the device-authorization flow, from this machine's side.
 //
 // It is the one subcommand that runs with no credential, so it takes its
@@ -59,14 +59,11 @@ export async function cmdLogin(opts) {
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const now = opts.now ?? (() => Date.now());
     const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
-    // Asked for, not assumed. The name is what an approver reads to tell one
-    // machine from another, and defaulting to the hostname without showing it is
-    // how two machines came to be called mbp2024 in production. --machine-name
-    // still wins outright; a terminal gets a pre-filled question; a headless run
-    // gets the hostname and is told so.
-    const machineName = await settleMachineName(opts.machineName, {
-        ...(opts.nameDeps ?? {}),
-    });
+    // The flag, validated, before anything is asked. `settleMachineName` returns
+    // it verbatim when it is given, so nothing below needs the prompt to know
+    // what the caller wants — and a malformed value should be refused before the
+    // command starts talking to a server.
+    const asked = opts.machineName === undefined ? undefined : validateMachineName(opts.machineName);
     // Said out loud on EVERY run, default or not. A default is convenient, and
     // the thing it takes away is the moment the operator typed the destination —
     // so the destination is printed instead. Nobody should have to guess which
@@ -98,8 +95,19 @@ export async function cmdLogin(opts) {
     // are repaired by retrying the IDEMPOTENT activate with what is already
     // stored, before opening a new grant — a fresh grant would instead collide
     // with the machine name the stored credential is holding.
+    //
+    // Read BEFORE the machine name is asked for. The prompt used to run first, so
+    // a machine that was already signed in was asked to name itself and only then
+    // told the question had no bearing — and the asking is not a wasted
+    // keystroke, it is a claim. Two people read it as evidence that the stored
+    // credential had been deleted, and went looking for a file that was on disk
+    // the whole time (#193).
+    //
+    // rc.2 checked first. #169 moved the prompt to the top of the command to
+    // reuse the name on both screens; nothing in it was about ordering, so
+    // nothing looked at the ordering.
     const stored = readCredential(originOf(endpoint), process.env);
-    if (stored && (opts.machineName === undefined || stored.machineName === machineName)) {
+    if (stored && (asked === undefined || stored.machineName === asked)) {
         const res = await post('/v1/device/activate', {}, stored.secret);
         if (res.ok) {
             process.stdout.write(`Already signed in as machine "${stored.machineName}".\n`);
@@ -114,6 +122,17 @@ export async function cmdLogin(opts) {
             throw new Error(`a credential for ${originOf(endpoint)} is stored but could not be activated (${res.status} ${code}) — not starting a new login on top of it`);
         }
     }
+    // Only now is the name needed: this run is opening a grant, so there really
+    // is a machine to name.
+    //
+    // Asked for, not assumed. The name is what an approver reads to tell one
+    // machine from another, and defaulting to the hostname without showing it is
+    // how two machines came to be called the same thing in production.
+    // --machine-name still wins outright; a terminal gets a pre-filled question;
+    // a headless run gets the hostname and is told so.
+    const machineName = await settleMachineName(opts.machineName, {
+        ...(opts.nameDeps ?? {}),
+    });
     const codeRes = await post('/v1/device/code', {
         client_id: CLIENT_ID,
         scope: 'login',

package/dist/src/commands/logout.js

@@ -0,0 +1,74 @@
+import { DEFAULT_ENDPOINT } from '../browser.js';
+import { originOf, removeCredentials } from '../credentials.js';
+import { clearRecordsForOrigin } from '../pending.js';
+/**
+ * The endpoint `logout` was asked for, or a refusal.
+ *
+ * The argv this command accepts is CLOSED — `[]`, or exactly
+ * `--endpoint <url>` — rather than filtered for the one flag it reads.
+ *
+ * Because it is destructive AND defaulted. Reading only `--endpoint` and
+ * ignoring the rest means `logout --endpont https://self.test` finds no flag,
+ * falls back to the hosted service, and deletes the production credential
+ * while the person believed they had named their own stack. So does
+ * `logout https://self.test`. Neither is an exotic input: they are a typo and
+ * a reasonable guess at the syntax.
+ *
+ * A command that removes a secret must not act on an argv it did not
+ * understand.
+ */
+export function logoutEndpoint(argv) {
+    const refuse = () => {
+        throw new Error('usage: agmsg-cloud logout [--endpoint <url>]');
+    };
+    if (argv.length === 0)
+        return undefined;
+    if (argv.length !== 2 || argv[0] !== '--endpoint')
+        return refuse();
+    const value = argv[1];
+    // A missing value would otherwise swallow the next token; there is no next
+    // token here, but the same shape (`--endpoint --force`) is what the flag
+    // reader elsewhere in this file guards against.
+    if (value.length === 0 || value.startsWith('--'))
+        return refuse();
+    try {
+        // Parsed here rather than at the point of deletion: an unparseable address
+        // should be refused before anything is read or removed.
+        void new URL(value);
+    }
+    catch {
+        return refuse();
+    }
+    return value;
+}
+export function cmdLogout(opts = {}) {
+    const env = opts.env ?? process.env;
+    const out = opts.out ?? ((text) => void process.stdout.write(text));
+    const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
+    const origin = originOf(endpoint);
+    const removed = removeCredentials(origin, env);
+    const pending = clearRecordsForOrigin(origin, env);
+    if (removed.length === 0) {
+        // Not an error. "There was nothing to remove" is the state someone running
+        // this twice is in, and the state someone checking is in — and it is the
+        // same end state they asked for. Exiting non-zero would make a script that
+        // signs out defensively fail on the run where it worked.
+        out(`No credential stored for ${origin}.\n`);
+        if (pending > 0)
+            out(`Cleared ${pending} pending enrollment record(s).\n`);
+        return;
+    }
+    // Named, not counted. The person signing out is entitled to know which
+    // identity just left this machine — one host can hold credentials for
+    // several orgs, and "signed out" without saying whose is how someone
+    // discovers later that the wrong one went.
+    for (const credential of removed) {
+        out(`Signed out machine "${credential.machineName}" from ${origin} (org ${credential.org}).\n`);
+    }
+    if (pending > 0)
+        out(`Cleared ${pending} pending enrollment record(s).\n`);
+    // Said because the omission is the surprising part: someone who ran this to
+    // clean up a machine should not have to wonder whether their history went
+    // with it.
+    out(`This machine's device key and local team keys were not touched.\n`);
+}

package/dist/src/commands/request.js

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createSasCommitment } from '@agmsg-cloud/sas-core';
-import { CourierClient } from '../api.js';
+import { CourierClient, CourierError } from '../api.js';
 import { recordAuthenticatedDigest } from '../authenticated-digest.js';
 import { CeremonyError, renderSasBlock, sasFromOpenedTranscript, waitForStatus } from '../ceremony.js';
 import { generateDeviceIdentity, publicKeyOf } from '../oss.js';
@@ -94,6 +94,36 @@ export async function cmdRequest(config, args, deps = {}) {
         }
     }
     if (!record || !requestId) {
+        // ASKED BEFORE THE ATTEMPT IS CHARGED, and that placement is the whole
+        // point. A device key that can never become a device on this account makes
+        // this ceremony unwinnable, and #194 is about such a path costing one of
+        // five. The server refuses it too — that check is the authority and stays
+        // — but it can only speak at the opening, by which time §4.1 has already
+        // spent the attempt.
+        //
+        // A REFUSAL BEFORE STARTING, NOT A REFUND AFTER. The difference matters:
+        // giving an attempt back because the server said the run did not count
+        // would let a hostile server hand out unlimited free ceremonies, which is
+        // exactly the budget an attacker wants while searching for a SAS
+        // collision. Declining to start costs the attacker nothing they cannot
+        // already do by refusing every request.
+        // The budget is READ before the lookup below, so a machine with nothing
+        // left still reaches the server for nothing. `consumeAttempt` remains the
+        // authority and re-checks under the lock — this only decides whether it is
+        // worth asking a question, and a sixth attempt must not reach the server
+        // at all, not even to read.
+        const before = readBudget(scope, env);
+        if (before.remaining === 0) {
+            writeErr(renderBudgetExhausted(before));
+            process.exitCode = 1;
+            return;
+        }
+        const blocked = await keyAlreadySpokenFor(client, pubkey);
+        if (blocked) {
+            writeErr(blocked);
+            process.exitCode = 1;
+            return;
+        }
         const { commitmentHex: plannedCommitment, openingNonce: plannedNonce } = createSasCommitment(pubkey);
         const charged = consumeAttempt(scope, plannedCommitment, env);
         if (!charged.ok) {
@@ -141,9 +171,15 @@ export async function cmdRequest(config, args, deps = {}) {
         // Derived here, from the two opened nonces. Nothing displayed below came
         // from the server as a code.
         const sas = sasFromOpenedTranscript(opened);
+        // The block says who decides, and says it once (#195). This printed a
+        // second copy immediately after it, so the screen read: who decides -> how
+        // to compare on a call you trust -> who decides. Repetition in the one
+        // screen where a single line has to be read is how the reader learns to
+        // skim it.
+        //
+        // The sentence was not deleted, it MOVED: what this copy carried and the
+        // block's did not — what a `no` means — is now the block's wording.
         out(renderSasBlock(sas, 'requester'));
-        out('  The approver decides. If they confirm, this machine is added and can\n' +
-            '  fetch its bundle; if not, nothing is sent and this request is over.\n\n');
         // The outcome is NOT known yet. Closing as succeeded here — which is what
         // this did — recorded every rejected ceremony as a success, so §4.1's
         // requirement that the requester counts failed and incomplete attempts, and
@@ -205,6 +241,131 @@ export async function cmdRequest(config, args, deps = {}) {
             process.exitCode = 1;
             return;
         }
+        // The two ways this machine's key cannot become a device on this account.
+        //
+        // They arrive at the OPENING — before any comparison — because that is the
+        // first moment the server has the key at all. They used to arrive as one
+        // `already_registered` at the very end, after an approver had been
+        // interrupted and had answered (#194), and it named neither case.
+        //
+        // A machine already on this account joining a second team is NOT here: that
+        // one succeeds now, which is what #194 was about.
+        if (err instanceof CourierError &&
+            (err.code === 'device_key_in_use' || err.code === 'device_key_changed')) {
+            done();
+            closeAttempt(scope, record.commitmentHex, 'failed', err.code, env);
+            writeErr(renderBudgetWarning(readBudget(scope, env)));
+            writeErr(await renderKeyRefusal(err.code, client, pubkey));
+            process.exitCode = 1;
+            return;
+        }
         throw err;
     }
 }
+// WHAT IS TRUE AT THIS POINT, and no more.
+//
+// This used to say "no approver was asked", which is false: reaching the
+// opening means the requester waited for `both_committed`, so an approver had
+// already run `approve` and posted a commitment over the bundle digest. They
+// were interrupted — what did NOT happen is the comparison and the upload
+// (raised in review). The test that blessed the old wording started its
+// scripted server at `both_committed` and so never ran the order it was
+// asserting about.
+const NOTHING_COMPARED = '  No digits were shown and no bundle was sent.\n';
+/**
+ * Whether this machine's key is already spoken for by a DIFFERENT machine, or
+ * this machine already holds a different key — asked before an attempt is spent.
+ *
+ * Returns the message to print, or null to go ahead. Best effort in one
+ * direction only: a lookup that fails, or a server too old to say which row is
+ * this machine's, returns null and lets the ceremony run. The server's own
+ * refusal is the gate; this exists to keep an unwinnable run from costing one
+ * of five, and a check that cannot answer must not become a second refusal on
+ * its own.
+ *
+ * `thisMachine === undefined` is not `false`. An older server says nothing
+ * about ownership, and reading silence as "none of these are yours" would
+ * refuse every ordinary rejoin.
+ */
+async function keyAlreadySpokenFor(client, pubkey) {
+    let devices;
+    try {
+        devices = await client.listDevices();
+    }
+    catch {
+        return null;
+    }
+    if (!devices.some((d) => d.thisMachine !== undefined))
+        return null;
+    const mine = devices.find((d) => d.thisMachine === true);
+    const holdingMyKey = devices.find((d) => d.devicePubkey === pubkey);
+    // The ordinary second-team case: this machine is on the account and the key
+    // it presents is its own. It still runs the full ceremony — what that
+    // establishes is this team's bundle digest, not the registration.
+    if (holdingMyKey && holdingMyKey.thisMachine === true)
+        return null;
+    if (holdingMyKey) {
+        return (`not started: this machine's device key is already registered to a different machine on\n` +
+            `  this account. It is listed as "${holdingMyKey.label}".\n\n` +
+            '  Two things look like this, and the machine you are sitting at tells them apart:\n\n' +
+            '    the same machine, signed in again under another name\n' +
+            '      -> an owner removes the OTHER entry in the console (Machines -> Remove).\n\n' +
+            "    a different machine, using a copy of that one's identity file\n" +
+            '      -> this machine needs its own. Move ~/.agmsg-cloud/device.key aside and\n' +
+            '         run this again; a new identity is generated when none is present.\n\n' +
+            '  No enrollment was started, so this costs none of your attempts.\n');
+    }
+    if (mine) {
+        return ('not started: this machine is already listed on the account under a different device key.\n' +
+            '  That happens when the key at ~/.agmsg-cloud/device.key was replaced or lost —\n' +
+            '  the listed one cannot be recovered from here, and the account still points at it.\n\n' +
+            '  To clear it, an owner removes this machine in the console (Machines -> Remove),\n' +
+            '  and then this machine signs in again with `agmsg-cloud login`.\n\n' +
+            '  No enrollment was started, so this costs none of your attempts.\n');
+    }
+    return null;
+}
+/**
+ * Why this machine's device key was refused, and what actually clears it.
+ *
+ * Both remedies were followed to the end before being printed. Removing a
+ * machine in the console revokes its capability URL AND its device rows
+ * (`revokeCapabilityRows`) and releases the machine slot, and both unique
+ * indexes are partial on active rows — so the next sign-in registers cleanly.
+ * It is an OWNER action, which is why the wording does not tell a member to go
+ * and do it.
+ */
+async function renderKeyRefusal(code, client, pubkey) {
+    if (code === 'device_key_changed') {
+        return ('not added: this machine is already listed on the account under a different device key.\n' +
+            '  That happens when the key at ~/.agmsg-cloud/device.key was replaced or lost —\n' +
+            '  the listed one cannot be recovered from here, and the account still points at it.\n\n' +
+            '  To clear it, an owner removes this machine in the console (Machines -> Remove),\n' +
+            '  and then this machine signs in again with `agmsg-cloud login`.\n' +
+            NOTHING_COMPARED);
+    }
+    // Naming the machine that holds the key turns "something is wrong" into one
+    // decision. It discloses nothing new: `listDevices` already answers any
+    // capability of this account with every device's label and public key.
+    //
+    // Best effort — a failed lookup must not replace the reason with an error
+    // about the lookup.
+    let holder = '';
+    try {
+        const held = (await client.listDevices()).find((d) => d.devicePubkey === pubkey);
+        if (held)
+            holder = ` It is listed as "${held.label}".`;
+    }
+    catch {
+        holder = '';
+    }
+    return (`not added: this machine's device key is already registered to a different machine on\n` +
+        `  this account.${holder}\n\n` +
+        '  Two things look like this, and the machine you are sitting at tells them apart:\n\n' +
+        '    the same machine, signed in again under another name\n' +
+        '      -> an owner removes the OTHER entry in the console (Machines -> Remove).\n\n' +
+        '    a different machine, using a copy of that one\'s identity file\n' +
+        '      -> this machine needs its own. Move ~/.agmsg-cloud/device.key aside and\n' +
+        '         run this again; a new identity is generated when none is present.\n\n' +
+        NOTHING_COMPARED);
+}

package/dist/src/commands/sync.js

@@ -1,12 +1,11 @@
-import { shellArg } from '../shell-arg.js';
-// Re-exported: the sync tests pinned the quoting rule through this module
-// before it had a home of its own, and those cases are still the ones that
-// prove the printed command survives a team name with a space in it.
-export { shellArg };
+import { existsSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { CourierClient } from '../api.js';
 import { originOf, readCredential } from '../credentials.js';
+import { publicKeyOf } from '../oss.js';
+import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
+import { shellArg } from '../shell-arg.js';
 import { cmdFetch } from './fetch.js';
 import { cmdPull } from './pull.js';
 import { cmdRequest } from './request.js';
@@ -64,7 +63,19 @@ export async function cmdSync(config, opts) {
     // this deliberately is not.
     try {
         const existing = await new CourierClient(config).listDevices();
-        const clash = existing.filter((d) => d.label === label);
+        // THIS MACHINE'S OWN ROW IS NOT A CLASH WITH ITSELF.
+        //
+        // The comparison was on label alone, so a machine already on the account —
+        // joining a second team — always matched itself and was warned that "this
+        // account already has a machine called <its own name>". That is the line
+        // read during the production walkthrough (#194), and acting on it means
+        // renaming a machine to avoid a collision with nothing.
+        //
+        // Identity is the device key, not the name. Absent before the first join,
+        // which is exactly when there is no own row to exclude.
+        const idPath = deviceIdentityPath();
+        const mine = existsSync(idPath) ? await publicKeyOf(idPath) : null;
+        const clash = existing.filter((d) => d.label === label && d.devicePubkey !== mine);
         if (clash.length > 0) {
             out(`  NOTE: this account already has ${clash.length === 1 ? 'a machine' : `${clash.length} machines`} called "${label}".\n`);
             out('  The approver sees names, so identical ones are indistinguishable on their screen.\n');

package/dist/src/commands/vault.js

@@ -2,7 +2,7 @@ import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { CourierClient } from '../api.js';
-import { keyHandoff, remoteBinding, unlockAuthenticatedBundle } from '../oss.js';
+import { connectedTeams, keyHandoff, remoteBinding, unlockAuthenticatedBundle } from '../oss.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
 import { generateRecoveryKey, normalizeRecoveryKey, promptRecoveryKey, showRecoveryKey, } from '../recovery-key.js';
 import { appendVaultVersionWithVdk, createVault, openVaultWithVdk, readAccountVault, vdkFromRecoveryKey, } from '../vault-protocol.js';
@@ -93,16 +93,87 @@ async function keepSlot(address, vdk) {
     process.stdout.write(`note: this machine could not keep a key slot (${saved.reason}), so the recovery ` +
         'key will be needed again next time.\n');
 }
-// `agmsg-cloud recovery setup <team>` — export the team's handoff bundle and store it
-// wrapped under the recovery key. The first run creates the vault and mints the
-// key; later runs append a version to the same vault under the same key.
+// Whether a team's material is the same material, judged on the key epochs the
+// bundle declares rather than on its bytes.
+//
+// The ciphertext differs every run (nonce), and whether the bundle itself is
+// byte-stable is not something this side has established — so neither can carry
+// the comparison. `key_ids` are the epochs, they are already stored per entry,
+// and they are exactly what "the key situation has not changed" means. Compared
+// as a set: the order the exporter lists them in is not part of the fact.
+/**
+ * The key that decides whether two records name the same team.
+ *
+ * One function, so both sides of every comparison are built the same way — a
+ * separator chosen twice is a separator that eventually differs. Framed rather
+ * than joined: `('a|b','c')` and `('a','b|c')` are different pairs and must not
+ * produce one key, which is the collision the request digest had to be fixed
+ * for. These two values are uuids today, so no pair can collide — the framing
+ * is here so that stays true if either ever stops being one.
+ *
+ * Written after the first version put a literal separator inside a template and
+ * a NUL character ended up in the source, which made the whole file binary to
+ * `grep`. Both sides still agreed, so nothing failed; the file simply stopped
+ * answering searches.
+ */
+function vaultTeamKey(serverInstanceId, teamId) {
+    return JSON.stringify([serverInstanceId, teamId]);
+}
+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]);
+}
+/**
+ * `recovery setup` — put the keys of every team THIS MACHINE reports into the
+ * account's vault.
+ *
+ * NO ARGUMENT IS THE ORDINARY FORM. The vault holds one recovery key for the
+ * whole account, so "set up recovery" is an account-level act; naming a team
+ * made it something to repeat every time a team was added, which is the folding
+ * this design exists to do. A team may still be named, for adding one on its
+ * own.
+ *
+ * NOT "every team on the account", and the difference is load-bearing until
+ * fujibee/agmsg#650 lands. The set comes from `remote.sh status --json`, which
+ * drops a team it could not read and exits 0 — so an active team that has never
+ * been backed up can be missed with nothing said. Every sentence describing this
+ * command, here and in `--help` and in the README, stops at what the machine
+ * reported for exactly that reason. Widening them is the change that closes
+ * #182, and it comes after #650, not before.
+ *
+ * IDEMPOTENT. A run where no team's epochs have moved writes nothing and leaves
+ * the revision where it was. `setup` that appended an identical version every
+ * time was a name promising one thing and a behaviour doing another — and the
+ * cost is not storage, it is that a version history exists to show when
+ * something changed, and identical versions make it unreadable.
+ */
 export async function cmdVaultPut(config, args) {
     // Same check connect gets. Without it a machine with no agmsg install runs
     // straight into `bash exited 127: …/remote.sh: No such file or directory` —
     // the same absence connect reports as a named checklist.
     ensurePreflight(preflight(config.scriptsDir, NEEDS.vaultPut));
     const client = new CourierClient(config);
-    const binding = await remoteBinding(config.scriptsDir, args.team);
+    // Two questions, and they are not the same one.
+    //
+    //   observed   every team whose status this machine could READ, whatever it
+    //              said. This is what makes "the vault holds a team that did not
+    //              appear" mean something: without it, a team disconnected here
+    //              is indistinguishable from one whose status could not be read.
+    //   targets    those with an ACTIVE binding. Only these may be filed — a
+    //              disconnected team's ids are a leftover, and a vault entry
+    //              under one records a backup against a remote this machine is no
+    //              longer bound to.
+    const observed = args.team === undefined ? await connectedTeams(config.scriptsDir) : [];
+    const targets = args.team === undefined
+        ? observed.filter((t) => t.state === 'active')
+        : [{ team: args.team, ...(await remoteBinding(config.scriptsDir, args.team)) }];
+    if (targets.length === 0) {
+        throw new Error('no team on this machine is connected to the hosted service, so there are no keys to back up.\n' +
+            'Run `agmsg-cloud connect <team>` first, or name a team if one is connected under a different name.');
+    }
     // The account's vault, not this team's: one vault, one recovery key. A second
     // team finds the vault that already exists and is added to it.
     const { identity, version } = await readAccountVault(client);
@@ -125,7 +196,7 @@ export async function cmdVaultPut(config, args) {
         // X" was true when a team had its own vault; saying it now would teach
         // someone to expect a different key per team, which is the belief the
         // account vault exists to remove.
-        const obtained = await vdkForVault(identity, version, args.team);
+        const obtained = await vdkForVault(identity, version, args.team ?? targets[0].team);
         vdk = obtained.vdk;
         askedForTheKey = obtained.usedRecoveryKey;
         // Open before writing. The container has to be read to add a team to it,
@@ -165,17 +236,127 @@ export async function cmdVaultPut(config, args) {
         await showRecoveryKey(minted, args.team);
         container = emptyContainer();
     }
+    // THE ENUMERATION IS NOT FAIL-CLOSED, AND THIS DOES NOT PRETEND TO FIX THAT.
+    //
+    // `remote.sh status --json` with no team DROPS a team it could not read and
+    // still exits 0, and the single-team form cannot tell "never connected" from
+    // "could not be read" either — same message, same exit code. Measured, and
+    // filed as fujibee/agmsg#650.
+    //
+    // The first version of this REFUSED when the vault held a team the run did
+    // not see. That was wrong, and the reason is worth keeping: a team
+    // deliberately disconnected here disappears from the enumeration too, and the
+    // vault keeps its entry forever by design — so the refusal fired every run,
+    // for the one reason that is not a problem, with no way out. Refusing on a
+    // distinction the system cannot draw treats "unknown" as "wrong".
+    //
+    // So it reports instead. What was not seen is put on the screen by name and
+    // the judgement goes back to the operator, who is the only party that knows
+    // whether they disconnected it. That leaves a real gap — nobody who does not
+    // read the output is protected — and the gap is smaller than a command that
+    // cannot be run.
+    //
+    // When #650 lands this can become a refusal again, because by then a team
+    // that could not be read will say so.
+    const seenThisRun = new Set(observed.map((t) => vaultTeamKey(t.serverInstanceId, t.teamId)));
+    const unseen = args.team === undefined
+        ? container.teams.filter((e) => !seenThisRun.has(vaultTeamKey(e.server_instance_id, e.team_id)))
+        : [];
+    // Seen, and deliberately not filed. Kept apart from `unseen` because they are
+    // different facts: this machine HEARD about these, and the ones above it did
+    // not hear about at all.
+    const disconnected = observed.filter((t) => t.state === 'disconnected');
+    // WHAT THIS RUN COVERED, BY NAME. Written once, so both exits below say the
+    // same thing — a sentence written twice is one that eventually disagrees with
+    // itself, and these two paths differ in everything else.
+    //
+    // NO COUNT WITHOUT ITS MEMBERS. What the operator saw on the production
+    // walkthrough was `stored revision 3 — team 'rc3walk' backed up; 2 teams`,
+    // and the "2 teams" never said which two. A count reads as "the account is
+    // backed up", which is wider than what was checked: the set came from what
+    // the local store reported, and that store can come back short without
+    // saying so (agmsg#650).
+    //
+    // The first version of this got it wrong in its own way — it printed the
+    // heading "Covered" and then listed only the DISCONNECTED teams, because the
+    // backed-up ones are not known until the loop below has run. Hence the
+    // parameters: the groups are passed in rather than closed over, so the
+    // heading cannot outrun what is under it.
+    const coverage = (written, unchanged) => {
+        const group = (title, members) => members.length === 0 ? [] : [`\n  ${title}\n`, ...members.map((m) => `    ${m}\n`)];
+        // The first two hold for either form — a run that names one team still has
+        // to say what it did with it. The rest are about the ENUMERATION, so they
+        // only mean anything when the enumeration is what chose the set.
+        const enumerated = args.team === undefined;
+        const lines = [
+            ...group('Backed up in this revision:', written),
+            ...group('Already current, nothing to write:', unchanged),
+            ...(!enumerated
+                ? []
+                : group('Disconnected on this machine, left as they are:', disconnected.map((t) => t.team))),
+            // Ids, because a team that never reported has no local name here to
+            // print — the same absence that put it on this list. Said plainly rather
+            // than dressed up as an instruction: this machine does not know whether
+            // these were disconnected on purpose, and the operator does.
+            ...(!enumerated
+                ? []
+                : group('In the vault, but not reported by this machine on this run:', unseen.map((e) => `${e.team_id}  (server ${e.server_instance_id})`))),
+        ];
+        if (unseen.length > 0) {
+            lines.push('\n  Those entries are untouched. If you disconnected them here, nothing is\n', '  wrong. If you did not, this machine could not read their state and they\n', '  were not re-checked — that is agmsg#650, and it cannot be told apart\n', '  from here.\n');
+        }
+        // Said only by the form that DERIVED its set. A run given a team covered
+        // what it was told to; claiming it covered what the store reported would
+        // be a statement about an enumeration that never ran.
+        if (enumerated) {
+            lines.push("\n  That is every team this machine's store reported. A team connected only\n", '  on another machine is backed up by running this there.\n');
+        }
+        return lines.join('');
+    };
     const scratch = mkdtempSync(join(tmpdir(), 'agmsg-cloud-'));
     try {
-        const bundleFile = join(scratch, 'handoff.bundle');
-        await keyHandoff(config.scriptsDir, args.team, bundleFile);
-        const bundle = readFileSync(bundleFile);
-        const next = upsertTeam(container, {
-            server_instance_id: binding.serverInstanceId,
-            team_id: binding.teamId,
-            key_ids: bundleKeyIds(bundle),
-            bundle: bundle.toString('base64'),
-        });
+        // One pass over every target. A team whose declared epochs already match
+        // what the vault holds is left exactly as it is — not re-sealed under a
+        // fresh nonce, which would be a new version saying nothing new.
+        let next = container;
+        const written = [];
+        const unchanged = [];
+        for (const [i, target] of targets.entries()) {
+            const bundleFile = join(scratch, `handoff-${i}.bundle`);
+            await keyHandoff(config.scriptsDir, target.team, bundleFile);
+            const bundle = readFileSync(bundleFile);
+            const keyIds = bundleKeyIds(bundle);
+            const already = next.teams.find((e) => e.server_instance_id === target.serverInstanceId && e.team_id === target.teamId);
+            if (already && sameEpochs(already.key_ids, keyIds)) {
+                unchanged.push(target.team);
+                continue;
+            }
+            next = upsertTeam(next, {
+                server_instance_id: target.serverInstanceId,
+                team_id: target.teamId,
+                key_ids: keyIds,
+                bundle: bundle.toString('base64'),
+            });
+            written.push(target.team);
+        }
+        // Nothing moved, and the vault already exists: there is no version to
+        // write. Saying "stored revision N+1" here would be true of the server and
+        // false about the account — the point of a revision is that something is
+        // different in it.
+        if (written.length === 0 && version && vdk) {
+            // The headline carries no bare count: what "up to date" covers is the
+            // list below it, and a number on its own is the thing this was reported
+            // for.
+            process.stdout.write(`already up to date — nothing has new keys. Revision stays at ${version.revision}.\n`);
+            process.stdout.write(coverage(written, unchanged));
+            // A run that had to type the key still earns a slot: the key is in hand,
+            // and the next run should not ask again just because this one had nothing
+            // to store.
+            if (askedForTheKey) {
+                await keepSlot(slotAddress(identity, version.vault_id, version.recovery_generation), vdk);
+            }
+            return;
+        }
         const content = serializeContainer(next);
         // The address this machine's slot is kept at, decided by which write
         // happened: an append addresses the vault that already exists, a create
@@ -196,10 +377,19 @@ export async function cmdVaultPut(config, args) {
             vdk = created.vdk;
             address = slotAddress(identity, created.vaultId, created.recoveryGeneration);
         }
-        const teamCount = next.teams.length;
-        process.stdout.write(`stored revision ${revision} — team '${args.team}' backed up` +
-            `${version ? '' : ' (vault created)'}; ` +
-            `${teamCount} team${teamCount === 1 ? '' : 's'} in this account's vault\n`);
+        // `; 2 teams in this account's vault` used to end this line. It is the
+        // count the walkthrough operator read and could not act on — it never said
+        // WHICH two, and a bare number here reads as a statement about the account
+        // rather than about what this run saw. The groups below say both.
+        process.stdout.write(`stored revision ${revision}${version ? '' : ' (vault created)'}\n`);
+        // WHAT WAS COVERED IS WHAT THIS MACHINE REPORTED, and that is what the line
+        // says. It used to end at the count above, which reads as "the account is
+        // backed up" — a claim wider than the thing that was checked, since the
+        // enumeration this ran on can come back short without saying so
+        // (agmsg#650). Teams already in the vault are covered by the refusal
+        // higher up; a team that has never been in it cannot be seen from here at
+        // all, so the sentence stops at the machine rather than the account.
+        process.stdout.write(coverage(written, unchanged));
         // After the write, and only when this run had to reach the key. A run the
         // slot already answered has a working slot at this address; saving again
         // would mint a fresh KEK, replace it, and touch the keychain on every

package/dist/src/credentials.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { closeSync, constants, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, chmodSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, chmodSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 /**
@@ -297,6 +297,48 @@ function writeLocked(path, dir, credential) {
         active: key,
         credentials: { ...file.credentials, [key]: credential },
     };
+    commit(path, dir, next);
+}
+/**
+ * Remove every credential this origin holds, and say which they were.
+ *
+ * Same lock and same durable write as a login, for the same reason: two
+ * processes that read before locking both write a stale base, and the loser's
+ * entry comes back from the dead. Removal has to be as careful as writing —
+ * a sign-out that half-worked leaves a secret on disk that its owner believes
+ * is gone.
+ *
+ * Returns what it removed rather than a count. The caller names the machine on
+ * screen, and the person signing out is entitled to know which identity just
+ * left this machine.
+ */
+export function removeCredentials(origin, env = process.env) {
+    const path = credentialsPath(env);
+    if (!existsSync(path))
+        return [];
+    const dir = dirname(path);
+    const release = acquireLock(path);
+    try {
+        const file = readFile(path);
+        const doomed = Object.entries(file.credentials).filter(([key]) => key.startsWith(`${origin} `));
+        if (doomed.length === 0)
+            return [];
+        const kept = Object.fromEntries(Object.entries(file.credentials).filter(([key]) => !key.startsWith(`${origin} `)));
+        // `active` is a KEY, and the key it names may be one of the ones going. A
+        // stale pointer would make `readCredential(null)` answer with a credential
+        // that is no longer in the file — null, not the first survivor: which org
+        // becomes current is the person's to say, and guessing it here would sign
+        // them into an account they did not choose.
+        const active = file.active && file.active in kept ? file.active : null;
+        commit(path, dir, { version: 1, active, credentials: kept });
+        return doomed.map(([, credential]) => credential);
+    }
+    finally {
+        release();
+    }
+}
+/** The atomic, durable write both paths share. Caller holds the lock. */
+function commit(path, dir, next) {
     // Unpredictable temp name: a name an attacker can guess is a name they can
     // pre-create as a symlink pointing somewhere else.
     const tmp = `${path}.${randomBytes(8).toString('hex')}.tmp`;

package/dist/src/index.js

@@ -5,6 +5,7 @@ import { cmdConnect, cmdConnectPreflight } from './commands/connect.js';
 import { cmdFetch } from './commands/fetch.js';
 import { cmdSync } from './commands/sync.js';
 import { cmdLogin } from './commands/login.js';
+import { cmdLogout, logoutEndpoint } from './commands/logout.js';
 import { cmdPull } from './commands/pull.js';
 import { cmdRequest } from './commands/request.js';
 import { cmdVaultPut, cmdVaultRestore } from './commands/vault.js';
@@ -16,6 +17,9 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
         [--endpoint <url>]     a self-hosted or development stack (default: the hosted service)
         [--machine-name <n>]   the name this machine is registered under (default: hostname)
 
+  logout                       remove this machine's stored credential for the service
+        [--endpoint <url>]     the same address login used (default: the hosted service)
+
   connect <team>               put a team this machine already runs onto the hosted service
   connect --preflight          check what connect needs, without connecting anything
 
@@ -28,15 +32,21 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
                                it is matched against the snapshot your code authenticated
   approve <team> [request-id]   (on a key-holding machine) approve the waiting request after the codes match
   watch [--interval-ms <n>]    (on a key-holding machine) print pending requests as they arrive
-  recovery setup <team>        create <team>'s recovery key and back the keys up under it
+  recovery setup [team]        create this account's recovery key and back up every active
+                               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>
   version                      the version of this CLI (also --version, -v)
                                the OSS scripts it drives are reported by
                                \`connect --preflight\`, which is a separate answer
 
 The recovery key is generated by \`recovery setup\` on the first run, shown once,
-and never stored anywhere. It is the only thing that opens the backup — if it is
-lost, so is the backup. After the first run, a machine with an OS secure store
+and never stored anywhere. There is ONE for the account, not one per team — which
+is why it is not something to repeat each time a team is added. What one run
+covers is every active team THIS MACHINE's store reports, and it names them when
+it finishes; a team connected only on another machine is backed up by running it
+there. It is the only thing that opens the backup — if it is lost, so is the
+backup. After the first run, a machine with an OS secure store
 keeps a key slot and does not ask for it again; a machine without one asks every
 time, and says so. It can only be typed at a terminal: there is no flag and no
 environment variable for it.
@@ -101,6 +111,16 @@ async function main(argv) {
                 ...(machineName === undefined ? {} : { machineName }),
             });
         }
+        case 'logout': {
+            // Local only, and its own subcommand rather than a flag on `login`: the
+            // two do opposite things, and a flag that inverts a command is how
+            // someone signs out while meaning to sign in.
+            // Closed argv, not a filtered read: this removes a secret and defaults
+            // to the hosted service, so an argument it does not understand must not
+            // become "the default one".
+            const endpoint = logoutEndpoint(rest);
+            return cmdLogout(endpoint === undefined ? {} : { endpoint });
+        }
         case 'connect': {
             // The dry run resolves no credential: its job is to be usable before
             // anything is set up.
@@ -191,14 +211,26 @@ async function main(argv) {
         case 'recovery': {
             const [sub, team] = rest;
             if (sub !== 'setup' && sub !== 'restore') {
-                throw new Error('usage: agmsg-cloud recovery <setup|restore> <team>');
+                // The two take different arguments, so one line covering both said the
+                // wrong thing about each: `setup` does not need a team and `restore`
+                // does. A usage message is read as the contract (raised in review).
+                throw new Error('usage: agmsg-cloud recovery setup [team]\n' +
+                    '       agmsg-cloud recovery restore <team>');
             }
+            // `setup` takes no team in its ordinary form: the vault is the ACCOUNT's,
+            // so setting it up covers every connected team, and naming one made it a
+            // thing to repeat each time a team was added. A team may still be given,
+            // 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.
-            if (!team) {
+            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>`);
             }
             const config = loadConfig();
-            return sub === 'setup' ? cmdVaultPut(config, { team }) : cmdVaultRestore(config, { team });
+            return sub === 'setup'
+                ? cmdVaultPut(config, team === undefined ? {} : { team })
+                : cmdVaultRestore(config, { team: team });
         }
         default:
             throw new Error(`unknown command: ${cmd}\n\n${USAGE}`);

package/dist/src/oss.js

@@ -28,6 +28,52 @@ function run(cmd, args, input) {
             child.stdin.end();
     });
 }
+/** A finished run, whatever its exit code. For callers where non-zero is an ANSWER. */
+function runAllowingFailure(cmd, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawnOssPiped(cmd, args);
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (d) => out.push(d));
+        child.stderr.on('data', (d) => err.push(d));
+        child.on('error', reject);
+        child.on('close', (code) => resolve({
+            code: code ?? -1,
+            stdout: Buffer.concat(out).toString(),
+            stderr: Buffer.concat(err).toString().trim(),
+        }));
+        child.stdin.end();
+    });
+}
+/**
+ * Whether this machine has a team by this name — the question `unlock` asks.
+ *
+ * NOT `remoteBinding`, and the difference was measured rather than assumed.
+ * `remoteBinding` additionally requires the binding to be ACTIVE, and against
+ * the real scripts:
+ *
+ *   team              status <team> --json     unlock <team>
+ *   connected         exit 0, state active     past the team check
+ *   DISCONNECTED      exit 0, state disconnected   past the team check
+ *   never existed     exit 1                   "agmsg: team not found"
+ *
+ * So a disconnected team is one `unlock` accepts and `remoteBinding` refuses.
+ * A caller that used the stricter check to decide whether a name is known would
+ * turn a working command into a refusal — which is the shape of defect this arc
+ * has already paid for twice. The exit code is the answer; the state is not.
+ *
+ * A non-zero exit is reported WITH what the store said, so a broken script does
+ * not get presented to the operator as a mistyped name.
+ */
+export async function localTeamLookup(scriptsDir, team) {
+    const r = await runAllowingFailure('bash', [
+        join(scriptsDir, 'remote.sh'),
+        'status',
+        team,
+        '--json',
+    ]);
+    return r.code === 0 ? { known: true, said: '' } : { known: false, said: r.stderr };
+}
 // Generate a device age identity at `identityPath`; returns its public recipient.
 export async function generateDeviceIdentity(identityPath) {
     await run('age-keygen', ['-o', identityPath]);
@@ -126,6 +172,49 @@ export async function remoteBinding(scriptsDir, team) {
     }
     return { teamId: status.remote_team_id, serverInstanceId: status.server_instance_id };
 }
+export async function connectedTeams(scriptsDir) {
+    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', '--json']);
+    const teams = [];
+    for (const line of out.toString().split('\n')) {
+        const text = line.trim();
+        if (text === '')
+            continue;
+        let status;
+        try {
+            status = JSON.parse(text);
+        }
+        catch {
+            // One unreadable line must not decide the whole answer either way:
+            // skipping it silently would file a backup that quietly omits a team, so
+            // it is refused instead. A status output this client cannot parse is not
+            // a shorter list of teams.
+            // Worded so it does not read as a command to paste: it quotes DATA, and
+            // the checker is right that an interpolation inside something
+            // command-shaped is worth refusing on sight.
+            throw new Error(`the team status this machine printed contains a line this version cannot read: ${JSON.stringify(text.slice(0, 80))}`);
+        }
+        // A state this version does not know is not quietly dropped and not quietly
+        // treated as filable: an unknown word here is the same shape as a line that
+        // did not parse, and it gets the same refusal.
+        if (status.state !== 'active' && status.state !== 'disconnected') {
+            throw new Error(`the team status this machine printed describes a state this version cannot read: ${JSON.stringify(String(status.state).slice(0, 40))}`);
+        }
+        if (typeof status.local_team !== 'string' ||
+            typeof status.remote_team_id !== 'string' ||
+            !status.remote_team_id ||
+            typeof status.server_instance_id !== 'string' ||
+            !status.server_instance_id) {
+            throw new Error(`remote.sh status --json described a team without the ids a vault entry needs`);
+        }
+        teams.push({
+            team: status.local_team,
+            teamId: status.remote_team_id,
+            serverInstanceId: status.server_instance_id,
+            state: status.state,
+        });
+    }
+    return teams;
+}
 export async function remoteTeamId(scriptsDir, team) {
     const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
     const text = out.toString().trim();

package/dist/src/pending.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { chmodSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { deriveApproverCommitment, isCanonicalAgeRecipient } from '@agmsg-cloud/sas-core';
@@ -296,3 +296,35 @@ export function listResumableRequesterRecords(serverOrigin, env = process.env) {
 export function clearRecord(input, env = process.env) {
     rmSync(recordPath(pendingDir(env), input.role, input.serverOrigin, input.key), { force: true });
 }
+/**
+ * Drop every pending record for one server, and say how many.
+ *
+ * For sign-out: a ceremony half-started against a service this machine is
+ * leaving has nothing left to complete, and its nonce is the opening of a
+ * commitment nobody will ever ask about again.
+ *
+ * Selected by the origin TAG that is already part of every filename, so this
+ * cannot drift from the naming above the way a second list of origins would.
+ * Records for other servers are untouched: signing out of one deployment is
+ * not signing out of the others.
+ */
+export function clearRecordsForOrigin(serverOrigin, env = process.env) {
+    const dir = pendingDir(env);
+    if (!existsSync(dir))
+        return 0;
+    const tag = originTag(serverOrigin);
+    let removed = 0;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        // `<role>-<tag>-<key>.json`. Matching the tag as its own dash-delimited
+        // field, not as a substring: a key that happened to contain the tag would
+        // otherwise take another server's record with it.
+        const parts = name.slice(0, -'.json'.length).split('-');
+        if (parts[1] !== tag)
+            continue;
+        rmSync(join(dir, name), { force: true });
+        removed += 1;
+    }
+    return removed;
+}

package/dist/src/recovery-key.js

@@ -1,5 +1,5 @@
 import { randomInt } from 'node:crypto';
-import { shellArg } from './commands/sync.js';
+import { shellArg } from './shell-arg.js';
 // The recovery key (K7) is the only thing that opens the vault. It is generated
 // here, shown once, and never stored — not by us and not by the server. Losing it
 // means the vault is unopenable, which is the property that makes the vault worth
@@ -289,12 +289,22 @@ export function promptRecoveryKey(prompt) {
 // 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 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) {
+    if (team === undefined)
+        return 'agmsg-cloud recovery setup';
+    return `agmsg-cloud recovery setup ${shellArg(team)}`;
+}
 export class NeedsTerminalError extends Error {
     constructor(team) {
         super('this needs a terminal, and stdin is not one.\n\n' +
             'Nothing was created and no recovery key exists yet. Run this yourself,\n' +
             'in your own terminal:\n\n' +
-            `    agmsg-cloud recovery setup ${shellArg(team)}\n\n` +
+            `    ${setupCommand(team)}\n\n` +
             'It is refused here on purpose: the recovery key is shown once and stored\n' +
             'nowhere, so writing it into a redirected or captured stream would be this\n' +
             'tool breaking that promise itself.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.3",
+  "version": "0.1.0-rc.4",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",