agmsg-cloud 0.1.0-rc.7 → 0.1.0

package/dist/src/commands/vault.js

@@ -2,12 +2,17 @@ import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { CourierClient } from '../api.js';
-import { connectedTeams, keyHandoff, remoteBinding, unlockAuthenticatedBundle } from '../oss.js';
+import { connectedTeams, keyHandoff, remoteBinding, runAllowingFailure, unlockAuthenticatedBundle, } from '../oss.js';
+import { cmdPull } from './pull.js';
+import { dataPlaneIdentity } from '../data-plane.js';
+import { originOf, readCredential } from '../credentials.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';
 import { openDeviceSlot, saveDeviceSlot } from '../device-slot.js';
 import { adviseOnSlot, renderSlotAdvice } from '../slot-advice.js';
+import { inventoryLines, inventoryOf, } from '../vault-inventory.js';
+import { placementLines } from '../vault-placement.js';
 import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertTeamIfMoved, } from '../vault-container.js';
 // The two recovery commands: resolve the team, obtain the bundle from the OSS
 // side, get the recovery key from the terminal, and hand off to
@@ -52,7 +57,13 @@ export function slotAddress(identity, vaultId, generation) {
  * the same place; what differs is what the person is told, and that judgement
  * lives in slot-advice.ts rather than here.
  */
-async function vdkForVault(identity, version, team) {
+async function vdkForVault(identity, version, 
+/**
+ * Optional: `restore` with no team has none to name, and the advice below is
+ * the only thing that used it. `setupCommand` already carries the no-team
+ * form, so the remedy stays executable either way.
+ */
+team) {
     const address = slotAddress(identity, version.vault_id, version.recovery_generation);
     const opened = await openDeviceSlot(address);
     if (opened.ok) {
@@ -61,7 +72,7 @@ async function vdkForVault(identity, version, team) {
         // does not fit. A check here would be a third place that has to agree.
         return { vdk: opened.vdk, usedRecoveryKey: false };
     }
-    const advice = renderSlotAdvice(adviseOnSlot(opened, { team }));
+    const advice = renderSlotAdvice(adviseOnSlot(opened));
     if (advice)
         process.stdout.write(advice);
     const recoveryKey = normalizeRecoveryKey(await promptRecoveryKey('Recovery key: '));
@@ -126,19 +137,11 @@ function vaultTeamKey(serverInstanceId, teamId) {
  * `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.
+ * The vault holds one recovery key for the whole account, so "set up recovery"
+ * is an account-level act. The old optional team argument existed while
+ * fujibee/agmsg#650 could silently omit an unreadable team. That producer now
+ * distinguishes the failure, so this command has one account-wide form and a
+ * short enumeration is refused rather than presented as a complete backup.
  *
  * 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
@@ -146,7 +149,7 @@ function vaultTeamKey(serverInstanceId, teamId) {
  * 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) {
+export async function cmdVaultPut(config) {
     // 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.
@@ -162,13 +165,11 @@ export async function cmdVaultPut(config, args) {
     //              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)) }];
+    const observed = await connectedTeams(config.scriptsDir);
+    const targets = observed.filter((t) => t.state === 'active');
     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.');
+            'Run `agmsg-cloud connect <team>` first.');
     }
     // 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.
@@ -192,7 +193,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 ?? targets[0].team);
+        const obtained = await vdkForVault(identity, version, targets[0].team);
         vdk = obtained.vdk;
         askedForTheKey = obtained.usedRecoveryKey;
         // Open before writing. The container has to be read to add a team to it,
@@ -229,35 +230,15 @@ export async function cmdVaultPut(config, args) {
         // becomes safe only when the slot is durable before the vault is created,
         // and that ordering is a separate change with its own failure to think
         // through (a slot addressed to a vault that was never made).
-        await showRecoveryKey(minted, args.team);
+        await showRecoveryKey(minted);
         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.
+    // agmsg#650 made unreadable status fail instead of silently disappearing, so
+    // `observed` is now a fail-closed account-wide enumeration. An old vault row
+    // can still be absent because this machine has no current binding for it;
+    // those rows remain untouched and are named below rather than deleted.
     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)))
-        : [];
+    const unseen = 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.
@@ -286,10 +267,6 @@ export async function cmdVaultPut(config, args) {
     // "Covered".
     const coverage = (written, unchanged, stranded) => {
         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),
@@ -299,26 +276,17 @@ export async function cmdVaultPut(config, args) {
             // that needs acting on — and the reason is what says which team's state
             // to look at, rather than leaving "something failed" for them to locate.
             ...group('Recorded as connected here, but this machine could not open them:', stranded.map((f) => `${f.team} — ${f.reason}`)),
-            ...(!enumerated
-                ? []
-                : group('Disconnected on this machine, left as they are:', disconnected.map((t) => t.team))),
+            ...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})`))),
+            ...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');
+            lines.push('\n  Those entries are untouched. If you disconnected them here, nothing is\n', '  wrong. This machine has no current binding to re-check for those ids.\n');
         }
+        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-'));
@@ -487,17 +455,14 @@ export async function cmdVaultPut(config, args) {
             //
             // Discarding the key is still right and still first: it opens nothing,
             // and someone who files it will trust it for years. What changed is the
-            // second half — a bare retry is only the answer when the cause was
-            // transient, and this exit does not know that it was. So it names the
-            // condition to check instead, and offers the narrow form, which is the
-            // one thing that lets an account with a broken leftover back up the team
-            // actually in use.
+            // second half — a bare retry is only the answer after the named cause is
+            // repaired. There is no per-team escape now: recovery setup is
+            // account-wide and refuses an incomplete backup (#182).
             process.stdout.write('\nThe backup did NOT complete, so the recovery key above was never used\n' +
                 'and opens nothing. Discard it.\n\n' +
-                'Re-running is only worth it if the cause above was temporary. If a team\n' +
-                'could not be opened, re-running will stop at the same place and cost you\n' +
-                'another key — back up the one you are using instead:\n\n' +
-                '    agmsg-cloud recovery setup <team>\n\n');
+                'Re-running before fixing the cause above will stop at the same place and\n' +
+                'cost you another key. Repair that team first, then run:\n\n' +
+                '    agmsg-cloud recovery setup\n\n');
         }
         throw err;
     }
@@ -530,9 +495,37 @@ export function bundleKeyIds(bundle) {
             'in the vault without them');
     }
 }
-// `agmsg-cloud recovery restore <team>` — pull the current version, open it with the
-// recovery key, and hand the bundle to the OSS unlock path.
-export async function cmdVaultRestore(config, args) {
+/**
+ * `agmsg-cloud recovery restore [team]` — open the account vault, and either
+ * unlock one named team from it or say what is in it.
+ *
+ * WITH A TEAM this is unchanged: resolve the local binding, open, select that
+ * team's entry, unlock. That path works on a machine that already has the team,
+ * and it is the one people use.
+ *
+ * WITHOUT ONE is the disaster path this command is named for, and it did not
+ * work at all. The binding lookup ran BEFORE the vault was ever read, so a
+ * machine that had lost everything got
+ *
+ *     agmsg: team 'x' has never been connected
+ *
+ * and stopped — measured against a stub endpoint that logs every request, which
+ * received nothing. The vault was never opened, so nothing could say what was
+ * in it, and a person with no local teams had no name to give that would have
+ * helped. Knowing the name was never the missing thing.
+ *
+ * So with no team the order is inverted: authenticate, open the vault, ask the
+ * control plane for names, and place what can be named — #342b. The order is
+ * forced, not chosen: `remote.sh unlock` requires the team to exist locally
+ * already (`remote.sh:1126`), so the bind (`pull`) comes before the unlock, and
+ * the vault has no names to bind with, so the names come before both.
+ *
+ * The team argument is kept and becomes "place just this one". Removing it is a
+ * decision available now that everything is placeable; it is not made here.
+ */
+export async function cmdVaultRestore(config, args = {}) {
+    if (args.team === undefined)
+        return placeFromVault(config);
     ensurePreflight(preflight(config.scriptsDir, NEEDS.vaultRestore));
     const client = new CourierClient(config);
     const binding = await remoteBinding(config.scriptsDir, args.team);
@@ -569,3 +562,277 @@ export async function cmdVaultRestore(config, args) {
         await keepSlot(slotAddress(identity, version.vault_id, version.recovery_generation), vdk);
     }
 }
+/**
+ * The no-team form: open the account vault and say what is in it.
+ *
+ * NO TEAM-LOCAL OSS STATE IS READ: no remote binding, no `remote.sh` preflight,
+ * no unlock. Those are the reads that fail on the machine this command exists
+ * to rescue — it has no teams, so every one of them ends the command before the
+ * vault is reached. `NEEDS.vaultRestore` requires `remote.sh` for the same
+ * reason it is skipped here: refusing to LIST a backup because the tool that
+ * PLACES one is missing is the same defect one layer out.
+ *
+ * IT DOES READ THIS MACHINE'S SECURE STORE, and that is deliberate.
+ * `vdkForVault` opens the device slot first; a machine that holds one is not
+ * asked for the recovery key, and a machine without one falls back to the
+ * recovery-key wrap. A replacement machine has no slot and types the key, which
+ * is the disaster path working as designed — the slot is an optimisation for
+ * machines that have already proven they hold this vault's key, not a
+ * prerequisite. Saying "nothing local" here was wider than what is true, and
+ * the check that was supposed to back it up did not look (review P1-artifact).
+ *
+ * The names come from the control plane, not from the vault, because the vault
+ * has none. That request uses the same credential the vault read just used, so
+ * it cannot introduce a new way to be unauthenticated — and if it fails, the
+ * inventory still reports every entry, as unnamed. A failure to name is not a
+ * failure to find.
+ */
+async function placeFromVault(config) {
+    const client = new CourierClient(config);
+    const { identity, version } = await readAccountVault(client);
+    if (!version) {
+        throw new Error('this account has no recovery vault yet — nothing to restore from');
+    }
+    const { vdk, usedRecoveryKey } = await vdkForVault(identity, version);
+    const opened = openVaultWithVdk(identity, version, vdk);
+    const container = parseContainer(opened.content);
+    // The slot is kept HERE, before any placing, and that moved.
+    //
+    // While this command only reported, saving at the end cost nothing. Now it
+    // spawns a `pull` and an `unlock` per team, and any of those can fail — so
+    // saving afterwards would mean a run that placed four teams and tripped on
+    // the fifth asks for the recovery key again next time. The moment this
+    // machine has proven it holds the vault's key is the moment the vault opened,
+    // which is here.
+    if (usedRecoveryKey) {
+        await keepSlot(slotAddress(identity, version.vault_id, version.recovery_generation), vdk);
+    }
+    const inv = inventoryOf(container, await serverNames(client));
+    for (const line of inventoryLines(inv, opened.revision)) {
+        process.stdout.write(`${line}\n`);
+    }
+    if (!inv.namesKnown) {
+        // Nothing is attempted, and the reason is the missing question rather than
+        // anything about the entries. Both `pull` and `unlock` are addressed by
+        // name; with no names there is no argument to give them.
+        process.stdout.write('nothing was placed: placing needs the names, and the server could not be asked\n');
+        return;
+    }
+    if (inv.named.length === 0) {
+        process.stdout.write('nothing here can be placed: none of these entries has a name\n');
+        return;
+    }
+    // Required only now. Listing a backup does not need the tool that places one
+    // — refusing to say what is in the vault because `remote.sh` is missing is
+    // the same defect one layer out — so the gate sits after the report and
+    // before the first spawn.
+    ensurePreflight(preflight(config.scriptsDir, NEEDS.vaultRestore));
+    const present = await teamsAlreadyHere(config.scriptsDir);
+    // WHICH SERVER, asked once, BEFORE anything is pulled.
+    //
+    // This was a post-pull check and that was not enough (review P1-1). A pull
+    // creates a local team under the person's name and gives it history, and the
+    // history is what makes the next pull refuse — measured. So discovering
+    // afterwards that the entry belonged to another server left a team that
+    // could not be replaced by the right one, with no way to free the name
+    // (#446). A restore that builds its own permanent obstacle is worse than one
+    // that places nothing.
+    //
+    // Only entries whose own instance matches are pulled at all. If the server
+    // cannot be asked, nothing is pulled: an unanswered question is not a match.
+    const endpoint = await endpointInstance(config, inv.named);
+    const results = [];
+    for (const named of inv.named) {
+        results.push(await placeOne(config, named, present, endpoint));
+    }
+    for (const line of placementLines(results, inv.total)) {
+        process.stdout.write(`${line}\n`);
+    }
+}
+/**
+ * The control plane's answer, or the fact that it had none.
+ *
+ * A failure to name is not a failure to find: the person is one step from
+ * having lost everything, and "here is what your backup holds, by id" is worth
+ * more than a stack trace. But it is not reported as an empty answer either —
+ * see `ServerNames`, which exists so this cannot be flattened into "the server
+ * mentioned none of them", which reads as "your credential cannot reach any of
+ * this".
+ */
+async function serverNames(client) {
+    try {
+        return { asked: true, teams: await client.listTeams() };
+    }
+    catch (err) {
+        process.stdout.write(`could not ask the server for team names (${err instanceof Error ? err.message : String(err)})\n`);
+        return { asked: false };
+    }
+}
+async function endpointInstance(config, named) {
+    if (named.length === 0)
+        return { known: false, why: 'there was nothing to place' };
+    const credential = readCredential(originOf(config.baseUrl));
+    if (!credential) {
+        return {
+            known: false,
+            why: `no stored credential for ${originOf(config.baseUrl)} — run \`agmsg-cloud login\` on this machine first`,
+        };
+    }
+    try {
+        // No team id is passed, and that is the point: naming one reaches a route
+        // that CLAIMS an unclaimed id on the hosted gateway. See `data-plane.ts`.
+        const { serverInstanceId } = await dataPlaneIdentity(credential.capabilityUrl);
+        return { known: true, serverInstanceId };
+    }
+    catch (err) {
+        return { known: false, why: err instanceof Error ? err.message : String(err) };
+    }
+}
+const remoteKey = (serverInstanceId, teamId) => `${serverInstanceId}${teamId}`;
+/**
+ * What this machine already holds, asked once.
+ *
+ * One `remote.sh status --json` for the whole loop rather than one per entry:
+ * the answer is a list, and asking per team would spawn a process per backup to
+ * learn what a single call already said.
+ *
+ * BOTH DIRECTIONS ARE KEPT, because the loop asks two different questions of
+ * the same answer — "is this backup already here (under any name)?" and "is
+ * this name taken by something else?" — and a single map answers only one.
+ *
+ * A team is matched on the PAIR. The same team id on a different instance is a
+ * different team, which is why the vault entry binds both.
+ */
+async function teamsAlreadyHere(scriptsDir) {
+    const byRemote = new Map();
+    const byName = new Map();
+    for (const t of await connectedTeams(scriptsDir)) {
+        // `disconnected` still counts as HERE — the question is whether the data is
+        // on this machine, and a re-pull would be refused for exactly that reason.
+        // But it does not count as unlockable: MEASURED, `remote.sh unlock` on a
+        // disconnected team exits 1 with `connected team binding is invalid or
+        // disconnected`, so the state is carried rather than flattened.
+        byRemote.set(remoteKey(t.serverInstanceId, t.teamId), {
+            team: t.team,
+            live: t.state === 'active',
+        });
+        byName.set(t.team, { teamId: t.teamId, instance: t.serverInstanceId });
+    }
+    return { byRemote, byName };
+}
+/**
+ * Place one entry: bind it if it is not here, then import its key.
+ *
+ * THE ORDER IS MEASURED, not assumed. `remote.sh pull` refuses a team with any
+ * local history BEFORE it compares team ids, so on a second run every team the
+ * first run placed comes back as `already has history; pull clones into an
+ * empty team` — a sentence that is right for `pull` and says nothing about a
+ * restore. So "is it already here" is decided from `remote.sh status --json`,
+ * which answers with both ids while the team is still locked, and `pull` is
+ * never called for a team that would be refused for that reason.
+ *
+ * `unlock` is safe to repeat: the OSS suite pins a second unlock with the same
+ * bundle at `imported 0 envelope(s)` and exit 0. It restarts that team's sync
+ * engine each time, so it is called once per entry and never in a retry.
+ */
+async function placeOne(config, { entry, team }, present, endpoint) {
+    // Under whatever local name it already has, which need not be the name the
+    // server uses now. Matching on the name instead would pull a second copy of a
+    // team this machine already holds.
+    const here = present.byRemote.get(remoteKey(entry.server_instance_id, entry.team_id));
+    const holder = present.byName.get(team);
+    if (here === undefined && holder !== undefined) {
+        return {
+            kind: 'name-held',
+            team,
+            teamId: entry.team_id,
+            instance: entry.server_instance_id,
+            localTeamId: holder.teamId,
+            localInstance: holder.instance,
+        };
+    }
+    if (here !== undefined && !here.live) {
+        // Not attempted: the unlock is known to refuse a disconnected binding, and
+        // reporting a call we knew would fail teaches the reader nothing about
+        // their own situation.
+        return { kind: 'disconnected', team: here.team, teamId: entry.team_id };
+    }
+    if (here === undefined) {
+        // BEFORE the pull, because the pull is what cannot be taken back.
+        if (!endpoint.known) {
+            return { kind: 'server-unknown', team, teamId: entry.team_id, why: endpoint.why };
+        }
+        if (endpoint.serverInstanceId !== entry.server_instance_id) {
+            return {
+                kind: 'wrong-instance',
+                team,
+                teamId: entry.team_id,
+                wanted: entry.server_instance_id,
+                got: endpoint.serverInstanceId,
+            };
+        }
+        const refused = await pullTeam(config, team, entry.team_id);
+        if (refused !== null)
+            return { kind: 'refused', team, teamId: entry.team_id, said: refused };
+        // THE PAIR IS CONFIRMED BEFORE THE KEY GOES IN. `listTeams` carries no
+        // server instance and the control plane cannot supply one — `team_id` is
+        // the primary key of `edge_team_claims` — so a name resolved there does not
+        // establish that the team it names lives on the server this backup came
+        // from. The binding the pull just wrote does, and it is read now because
+        // the NEXT step is the one that would install this server's key material
+        // into a different server's team.
+        const bound = await remoteBinding(config.scriptsDir, team);
+        if (bound.serverInstanceId !== entry.server_instance_id ||
+            bound.teamId !== entry.team_id) {
+            return {
+                kind: 'wrong-instance',
+                team,
+                teamId: entry.team_id,
+                wanted: entry.server_instance_id,
+                got: bound.serverInstanceId,
+            };
+        }
+    }
+    const localName = here?.team ?? team;
+    const failed = await unlockTeam(config, localName, entry.bundle);
+    if (failed !== null)
+        return { kind: 'locked', team: localName, teamId: entry.team_id, said: failed };
+    return here === undefined
+        ? { kind: 'placed', team: localName, teamId: entry.team_id }
+        : { kind: 'already', team: localName, teamId: entry.team_id };
+}
+/** Returns what `remote.sh` said when it refused, or null when the pull worked. */
+async function pullTeam(config, team, teamId) {
+    let said = '';
+    // Piped rather than inherited: this is a loop, and each team's output belongs
+    // under that team in the report. What comes back is printed as it arrived —
+    // the OSS side is the one that knows why it refused, and a paraphrase here is
+    // a second copy of its wording that goes stale.
+    const runner = async (command, args) => {
+        const r = await runAllowingFailure(command, [...args]);
+        said = [r.stdout.trim(), r.stderr.trim()].filter((s) => s !== '').join('\n');
+        return r.code;
+    };
+    try {
+        await cmdPull(config, { team, teamId, runner, nextStepsFromCaller: true });
+        return null;
+    }
+    catch (err) {
+        // `said` is empty when the failure was this side's — an unresolvable
+        // credential, say — and then our own message is the only account there is.
+        return said !== '' ? said : err instanceof Error ? err.message : String(err);
+    }
+}
+/** Returns what failed, or null when the key imported. */
+async function unlockTeam(config, team, bundle) {
+    try {
+        // Straight from the vault's bytes into the OSS import, with no file in
+        // between — the same reason the one-team path does it this way: a path can
+        // be made to point at other bytes after we vouched for these ones.
+        await unlockAuthenticatedBundle(config.scriptsDir, team, Buffer.from(bundle, 'base64'));
+        return null;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}

package/dist/src/commands/watch.js

@@ -10,6 +10,30 @@ import { shellArg } from '../shell-arg.js';
 // not revealed until an approver has committed. Anything shown here would have
 // to be invented, and a code that appears before the ceremony has run is exactly
 // the thing a user must never learn to accept.
+/**
+ * The line one waiting request is announced with.
+ *
+ * Split out so it can be read by a test. `cmdWatch` writes straight to
+ * `process.stdout` and takes no sink, so the only other way to check what it
+ * says is a global spy on the stream — which this suite has already paid for
+ * once: a spy installed for one file leaked into three others and timed them
+ * out. A pure function is the seam that costs nothing.
+ */
+export function watchLine(req) {
+    return (
+    // The id is the server's, not ours, and it lands in an argument
+    // position of a line written to be pasted. Quoted for that reason
+    // rather than because a UUID needs it: what makes a value safe here is
+    // where it goes, not what it happens to contain today.
+    //
+    // ONCE, not twice. The id opened this line as well until #329 — the
+    // same value, in a position where nothing can be done with it, three
+    // words before the position where it is the argument to paste. This is
+    // the one place in the CLI where a record id passes #275's test, and it
+    // passes it by being part of the next step rather than by being shown.
+    `enrollment request "${req.label}" — run \`agmsg-cloud approve <team> ${shellArg(req.id)}\` ` +
+        `to compare codes with them (expires ${req.expires_at})\n`);
+}
 export async function cmdWatch(config, args, deps = {}) {
     const client = new CourierClient(config);
     const interval = args.intervalMs ?? 15_000;
@@ -32,13 +56,7 @@ export async function cmdWatch(config, args, deps = {}) {
             if (seen.has(req.id))
                 continue;
             seen.add(req.id);
-            process.stdout.write(
-            // The id is the server's, not ours, and it lands in an argument
-            // position of a line written to be pasted. Quoted for that reason
-            // rather than because a UUID needs it: what makes a value safe here is
-            // where it goes, not what it happens to contain today.
-            `enrollment request ${req.id} "${req.label}" — run \`agmsg-cloud approve <team> ${shellArg(req.id)}\` ` +
-                `to compare codes with them (expires ${req.expires_at})\n`);
+            process.stdout.write(watchLine(req));
         }
         if (deps.signal?.aborted)
             break;

package/dist/src/config.js

@@ -80,7 +80,11 @@ export function defaultScriptsDir(home = homedir()) {
  * review again). One body, so there is nothing to keep in step.
  */
 function resolveCredential(env) {
-    return fromEnv(env) ?? readCredential(null, env);
+    const viaEnv = fromEnv(env);
+    if (viaEnv)
+        return { ...viaEnv, from: 'env' };
+    const stored = readCredential(null, env);
+    return stored ? { ...stored, from: 'stored' } : null;
 }
 /**
  * Whether this machine has a credential to act with — `loadConfig`'s own
@@ -99,5 +103,10 @@ export function loadConfig(env = process.env) {
     if (!resolved) {
         throw new Error('not signed in on this machine — run `agmsg-cloud login --endpoint <url>` first');
     }
-    return { baseUrl: resolved.endpoint, secret: resolved.secret, scriptsDir: resolveScriptsDir(env) };
+    return {
+        baseUrl: resolved.endpoint,
+        secret: resolved.secret,
+        scriptsDir: resolveScriptsDir(env),
+        credentialFrom: resolved.from,
+    };
 }