agmsg-cloud 0.1.0-rc.8 → 0.1.1

package/dist/src/preflight.js

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { defaultScriptsDir, hasCredential, scriptsDirChoice } from './config.js';
 import { join } from 'node:path';
 import { platform } from 'node:process';
+import { selfInstall } from './self-install.js';
 // What `connect` needs before it starts, checked all at once.
 //
 // Everything here is reported together. Finding one missing thing, installing
@@ -23,13 +24,13 @@ import { platform } from 'node:process';
 // documented answer to "what is installed here", and reaching past it would
 // bind us to a layout that is not ours.
 //
-// Reported, not compared. The string is a git-describe (`v1.1.11-320-gfbc90db`)
-// for an install taken from a branch, and a plain tag for a released one — and
-// those two do not order against each other. The dogfood install measures as
-// `v1.1.11-320-…` while the released `v1.1.13` has no remote sync at all, so a
-// numeric floor would reject the only install that can currently connect.
-// Until there is a released version to compare against, this is shown for
-// diagnosis and nothing is gated on it.
+// Connect capability is still probed directly rather than inferred from this
+// string: branch describe strings and older stable releases do not order by
+// the remote-sync features they contain. Account-wide recovery setup has one
+// narrower exception. fujibee/agmsg#650 first shipped in v1.2.0-rc.4, so that
+// command uses the release as a floor for the fail-closed status producer.
+// Unknown or unparseable provenance is rejected for that command because it
+// cannot establish that a silently short team list is impossible.
 export function installedVersion(scriptsDir) {
     try {
         const out = execFileSync('bash', [join(scriptsDir, 'version.sh')], {
@@ -42,6 +43,33 @@ export function installedVersion(scriptsDir) {
         return null;
     }
 }
+/**
+ * Whether the installed OSS status producer refuses a silently short team set.
+ *
+ * fujibee/agmsg#650 first shipped in v1.2.0-rc.4. Before that,
+ * `remote.sh status --json` could omit an unreadable team and exit 0, which is
+ * unsafe for account-wide recovery setup. Unknown and non-release provenance
+ * strings fail closed: rejecting an install we cannot order is cheaper than
+ * presenting a partial backup as complete.
+ */
+export function supportsFailClosedTeamStatus(version) {
+    if (version === null)
+        return false;
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-rc\.(\d+)(?:-\d+-g[0-9a-f]+)?|-\d+-g[0-9a-f]+)?$/.exec(version);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    const rc = match[4] === undefined ? null : Number(match[4]);
+    if (major !== 1)
+        return major > 1;
+    if (minor !== 2)
+        return minor > 2;
+    if (patch !== 0)
+        return patch > 0;
+    return rc === null || rc >= 4;
+}
 // Does the installed remote.sh offer `connect`? Asked of the script itself: run
 // with no arguments it prints its usage, which names the subcommands it has.
 //
@@ -117,7 +145,11 @@ const PYTHON_INSTALL = [
 //                     recovery restore
 export const NEEDS = {
     connect: { command: 'connect', scripts: ['remote.sh'], requireConnect: true },
-    vaultPut: { command: 'recovery setup', scripts: ['remote.sh', 'key.sh'] },
+    vaultPut: {
+        command: 'recovery setup',
+        scripts: ['remote.sh', 'key.sh'],
+        requireFailClosedTeamStatus: true,
+    },
     vaultRestore: { command: 'recovery restore', scripts: ['remote.sh'] },
     fetch: { command: 'fetch', scripts: ['remote.sh', 'remote-sync.sh'] },
     approve: { command: 'approve', scripts: ['key.sh', 'remote-sync.sh'] },
@@ -161,9 +193,21 @@ export function preflight(scriptsDir, needs, env = process.env,
  * `homedir()` does not return — reading it would have moved the default
  * install for every Git Bash user in exchange for a testable line.
  */
-home) {
+home, 
+/**
+ * How the `agmsg-cloud` on PATH is asked which copy it is.
+ *
+ * A SEAM, and it earned itself immediately: the real one SPAWNS that binary,
+ * and the tests below call `preflight()` with the machine's own environment.
+ * Six of them started timing out at 5000ms the moment this block existed,
+ * because they were waiting on whatever `agmsg-cloud` happens to be installed
+ * on the machine running the suite. A check about tool prerequisites should
+ * not depend on the tester's PATH.
+ */
+versionRunner) {
     const { command, scripts } = needs;
     const requireConnect = needs.requireConnect ?? false;
+    const requireFailClosedTeamStatus = needs.requireFailClosedTeamStatus ?? false;
     const requirements = [];
     // BEING SIGNED IN IS A PREREQUISITE, so it is one of the things checked.
     //
@@ -190,13 +234,12 @@ home) {
     // a different kind of thing (install agmsg, or point AGMSG_SCRIPTS_DIR at it)
     // than installing a binary.
     const missingScripts = scripts.filter((s) => !existsSync(join(scriptsDir, s)));
-    // Present AND able to do the thing. A version number would be the obvious
-    // check and is the wrong one: `version.sh` returns a git-describe string, so
-    // the install that can connect measures as v1.1.11-320-g… while a released
-    // v1.1.13 without remote sync measures as newer. A numeric floor would reject
-    // the only install that works. So the capability is asked for directly.
+    // Present AND able to do the thing. Connect is asked as a capability rather
+    // than inferred from a version; account-wide recovery separately applies the
+    // released producer floor described above `installedVersion`.
     const scriptsPresent = missingScripts.length === 0;
     const canConnect = scriptsPresent && (!requireConnect || remoteSupportsConnect(scriptsDir));
+    const agmsgVersion = scriptsPresent ? installedVersion(scriptsDir) : null;
     requirements.push({
         name: requireConnect
             ? `agmsg with remote sync (in ${scriptsDir})`
@@ -210,6 +253,14 @@ home) {
             'Elsewhere?           point AGMSG_SCRIPTS_DIR at that install\'s scripts directory.',
         ],
     });
+    if (requireFailClosedTeamStatus) {
+        requirements.push({
+            name: 'agmsg with fail-closed team status',
+            ok: scriptsPresent && supportsFailClosedTeamStatus(agmsgVersion),
+            why: 'recovery setup backs up the account-wide set. This install cannot be confirmed as v1.2.0-rc.4 or newer, where an unreadable team stopped disappearing from `remote.sh status --json` as a successful short list.',
+            install: ['Install or update:   npx agmsg install'],
+        });
+    }
     const tools = toolsFor(scripts);
     requirements.push({
         name: 'age and age-keygen',
@@ -238,9 +289,20 @@ home) {
         ok: requirements.every((r) => r.ok),
         command,
         scriptsDir,
-        agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
+        agmsgVersion: canConnect ? agmsgVersion : null,
         scriptsDirFrom: provenance(env, home),
         otherInstalls: otherInstalls(scriptsDir, env, home),
+        // Never fatal. A preflight that refused to run because it could not
+        // identify ITSELF would withhold the tool checks — the thing the operator
+        // actually came for — over a diagnostic about the tool.
+        self: (() => {
+            try {
+                return selfInstall(env, undefined, versionRunner ?? (() => null));
+            }
+            catch {
+                return null;
+            }
+        })(),
     };
 }
 /**
@@ -347,6 +409,69 @@ export function formatPreflight(result) {
         lines.push('');
         lines.push(`  agmsg reports itself as: ${result.agmsgVersion}`);
     }
+    // AND WHICH `agmsg-cloud` IS SAYING ALL THIS (#341).
+    //
+    // Everything above is this binary reporting on another install. The binary
+    // itself went unreported, and that is the expensive gap: on a machine holding
+    // both an npm and a pnpm global copy, the install succeeds, the version the
+    // operator gets is whichever package manager put its bin directory earlier on
+    // PATH, and nothing errors.
+    //
+    // Printed on EVERY run, not only when there is a conflict. The version line
+    // is what makes an operator's report usable by anyone else, and the shadowing
+    // case is invisible precisely because nothing looks wrong — a section that
+    // appeared only on trouble would be missing from every report written before
+    // anyone suspected trouble.
+    if (result.self !== null) {
+        const self = result.self;
+        lines.push('');
+        // NOT `agmsg-cloud ${version}`, which was the first spelling and which the
+        // printed-command checker refused: a line that opens with the binary name
+        // and interpolates a value is command-shaped, and a command-shaped line in
+        // output is one someone pastes. The label form says the same thing and
+        // cannot be run.
+        lines.push(`  this agmsg-cloud is:     ${self.version}`);
+        lines.push(`  running from:            ${self.directory}`);
+        if (self.winner === 'none') {
+            // Reachable: an npx run, or a direct `node dist/src/index.js`. Worth
+            // saying rather than omitting, because "typing the name runs this" is the
+            // assumption the console's instruction creates, and here it is false in
+            // the other direction — typing the name runs nothing.
+            lines.push(`  no agmsg-cloud on PATH — this was not started by typing its name.`);
+        }
+        else {
+            const first = self.onPath[0];
+            lines.push(`  typing the name runs:    ${first}`);
+            if (self.winner === 'elsewhere') {
+                // THE ONE THIS SECTION EXISTS FOR, and the claim is now a measurement
+                // rather than an inference: that binary was RUN, and it named a
+                // different directory as the one it came from. Still not "you are
+                // running an old version" — the version it reported is its own business
+                // and this line does not repeat it; what the operator needs is that the
+                // name does not reach this build.
+                lines.push(`  THAT IS NOT THIS COPY. Another agmsg-cloud is earlier on PATH and wins.`);
+                lines.push(`  remove the one you do not want — a second install does not error.`);
+            }
+            else if (self.winner === 'unresolved') {
+                // It could not be run, or could not be read: a spawn failure, a
+                // timeout, or a release old enough to print one record instead of two —
+                // which is every published version at the time of writing. None of
+                // those is evidence of a different copy, so no claim is made and the
+                // reader is handed the question.
+                lines.push(`  whether that is this copy could not be determined from here.`);
+                lines.push(`  run agmsg-cloud -v in a new shell and compare it with the version above.`);
+            }
+            if (self.onPath.length > 1) {
+                // The rest of the list, because "another one is earlier" prompts "where
+                // are they all", and a PATH search is the thing the operator would do
+                // next by hand. First already named above, so the label says which.
+                lines.push('');
+                for (const other of self.onPath.slice(1)) {
+                    lines.push(`  also on PATH, later:     ${other}`);
+                }
+            }
+        }
+    }
     const missing = result.requirements.filter((r) => !r.ok);
     if (missing.length === 0) {
         lines.push('');

package/dist/src/recovery-key.js

@@ -1,5 +1,4 @@
 import { randomInt } from 'node:crypto';
-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
@@ -310,24 +309,20 @@ export function promptRecoveryKey(prompt) {
 /**
  * How this tool names the command that creates a vault and backs teams up.
  *
- * One derivation, because the argument convention has already moved once: the
- * team used to be required and is now optional, and the no-argument form is the
- * ordinary one — it covers every team this machine reports rather than the one
- * that happened to be in hand. Every place that prints this remedy asks here,
- * so the next change to the convention moves one line rather than being grepped
- * for (#181).
+ * One derivation, because the argument convention has already moved twice: the
+ * team used to be required, then optional while agmsg#650 made the broad
+ * enumeration unsafe, and now absent. Recovery belongs to the account, and
+ * every printed remedy uses the account-wide command (#182).
  */
-export function setupCommand(team) {
-    if (team === undefined)
-        return 'agmsg-cloud recovery setup';
-    return `agmsg-cloud recovery setup ${shellArg(team)}`;
+export function setupCommand() {
+    return 'agmsg-cloud recovery setup';
 }
 export class NeedsTerminalError extends Error {
-    constructor(team) {
+    constructor() {
         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' +
-            `    ${setupCommand(team)}\n\n` +
+            `    ${setupCommand()}\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.');
@@ -364,17 +359,17 @@ export function recoveryKeyNotice(key) {
         'machine, not the server, not support.\n' +
         '\n');
 }
-export async function showRecoveryKey(key, team) {
+export async function showRecoveryKey(key) {
     // Checked BEFORE the key reaches stdout, which is the whole point. Showing
     // first and then discovering there is nobody to acknowledge means the only
     // copy of the key is already in whatever the output was redirected to —
-    // `recovery setup <team> > log.txt` would write it to a file and report
+    // `recovery setup > log.txt` would write it to a file and report
     // success, which is the opposite of "shown once, stored nowhere".
     //
     // Nothing has been created at this point, so refusing here leaves no vault
     // and no key in use. The message says what to run instead.
     if (!process.stdin.isTTY || typeof process.stdin.setRawMode !== 'function') {
-        throw new NeedsTerminalError(team);
+        throw new NeedsTerminalError();
     }
     process.stdout.write(recoveryKeyNotice(key));
     await confirmSaved();

package/dist/src/self-install.js

@@ -0,0 +1,152 @@
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, existsSync, realpathSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { platform } from 'node:process';
+import { packageInstall } from './version.js';
+import { parseVersionOutput } from '../scripts/version-output.js';
+// WHICH `agmsg-cloud` ANSWERS WHEN SOMEONE TYPES IT (#341).
+//
+// The console tells everyone to run `npm i -g agmsg-cloud`. On a machine that
+// also has a pnpm global install, that succeeds and a different binary answers:
+// measured on a real machine, `npm i -g` reported success, `npm ls -g` showed
+// rc.7, and `agmsg-cloud -v` said rc.5, because the pnpm bin directory sits
+// earlier on PATH. Nothing errored. The operator then spent a walk meeting two
+// defects that were fixed in the version they had installed and were not
+// running.
+//
+// This is #282 one level up. #317 made `--preflight` name the `agmsg` install
+// and what chose it; nothing reported on the `agmsg-cloud` binary doing the
+// reporting. The expensive failure mode is the same one: THE WRONG INSTALL
+// ANSWERS CORRECTLY.
+//
+// TWO DIFFERENT QUESTIONS, and `version.ts` already says so in as many words:
+// `which agmsg-cloud` answers from PATH, and a manifest answers from the module
+// graph. This module is where the two are asked side by side, because the whole
+// defect is that they can disagree while everything reports success.
+//
+// DERIVING THE CANDIDATES MATTERS MORE HERE than it did for `agmsg`, and the
+// issue says why: `resolveScriptsDir` takes an env var or a default and never
+// searches, so there were exactly two places to look. PATH is a list, and the
+// answer is whichever comes first.
+/** The names a PATH entry can carry on this platform. */
+function executableNames() {
+    // On Windows a bare `agmsg-cloud` is not executable; npm writes `.cmd` (and
+    // pnpm a `.CMD`/`.ps1` pair) beside it. PATHEXT is the general rule and this
+    // is not it — it is the two names this package's installers actually write.
+    // Stated as a limit rather than implied: a Windows install under some other
+    // extension is not found here, and `pathScanComplete` reports that this scan
+    // is name-based so a reader is not told a bounded list is an exhaustive one.
+    return platform === 'win32' ? ['agmsg-cloud.cmd', 'agmsg-cloud.exe', 'agmsg-cloud'] : ['agmsg-cloud'];
+}
+/**
+ * Would a shell run this file, or merely find it?
+ *
+ * The scan asked `isFile()` alone in the first version, so a PATH directory
+ * holding a non-executable `agmsg-cloud` — a leftover, a half-finished copy, a
+ * file someone saved there — was reported as the thing `typing the name runs`
+ * (raised in review). It is not: a shell skips it and keeps walking. This whole
+ * block's claim is about what RUNS, not about which directories contain a
+ * matching name, so finding is the wrong question to stop at.
+ *
+ * `X_OK` rather than a mode-bit test, because "executable" is a question about
+ * this process's effective user and its groups, not about `0o111` being set
+ * somewhere in the mode. On Windows `access` reports every existing file as
+ * executable, which is why the name and extension list above carries that
+ * platform's rule instead.
+ */
+function runnable(candidate) {
+    if (platform === 'win32')
+        return true;
+    try {
+        accessSync(candidate, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every `agmsg-cloud` on PATH, in PATH order.
+ *
+ * FIRST WINS, and that is the whole reason the order is preserved rather than
+ * sorted or deduplicated into a set. The list is what a shell would walk, and
+ * the answer to "what runs when I type the name" is its first element.
+ *
+ * A directory that appears twice on PATH yields its entry twice; that is left
+ * as it is, because a PATH with duplicates is itself worth seeing when someone
+ * is trying to work out why the wrong copy answers.
+ */
+export function agmsgCloudOnPath(env = process.env) {
+    const raw = env['PATH'] ?? env['Path'] ?? '';
+    const found = [];
+    for (const dir of raw.split(delimiter)) {
+        if (dir === '')
+            continue;
+        for (const name of executableNames()) {
+            const candidate = join(dir, name);
+            try {
+                if (existsSync(candidate) && statSync(candidate).isFile() && runnable(candidate)) {
+                    found.push(candidate);
+                    break;
+                }
+            }
+            catch {
+                // A PATH entry that cannot be stat'ed — a dead mount, a permission
+                // wall — is not a candidate and is not an error worth ending the scan
+                // for. The next entry may well be the one that answers.
+            }
+        }
+    }
+    return found;
+}
+export function selfInstall(env = process.env, moduleUrl, 
+/**
+ * How to ask the binary which copy it is. Defaults to NOT ASKING.
+ *
+ * A default that spawns would put an extra process in front of every
+ * `connect`, and this is a diagnostic for the screen someone opens when they
+ * are confused — not a tax on the path that is working. `cmdConnectPreflight`
+ * passes `runVersion`; the check that runs before a real connect does not.
+ */
+run = () => null) {
+    const install = moduleUrl === undefined ? packageInstall() : packageInstall(moduleUrl);
+    const onPath = agmsgCloudOnPath(env);
+    return { ...install, onPath, winner: winnerOf(onPath[0], install.directory, run) };
+}
+export const runVersion = (binary) => {
+    try {
+        return execFileSync(binary, ['--version'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            // Bounded, because this runs inside a preflight someone is waiting on and
+            // the thing being spawned is by definition a binary this build knows
+            // nothing about.
+            timeout: 5000,
+        });
+    }
+    catch {
+        return null;
+    }
+};
+function winnerOf(first, directory, run) {
+    if (first === undefined)
+        return 'none';
+    const printed = run(first);
+    if (printed === null)
+        return 'unresolved';
+    const parsed = parseVersionOutput(printed.trim());
+    if (!parsed.ok)
+        return 'unresolved';
+    const same = (a, b) => {
+        const real = (p) => {
+            try {
+                return realpathSync(p);
+            }
+            catch {
+                return p;
+            }
+        };
+        return real(a) === real(b);
+    };
+    return same(parsed.directory, directory) ? 'this' : 'elsewhere';
+}

package/dist/src/slot-advice.js

@@ -1,5 +1,4 @@
 import { setupCommand } from './recovery-key.js';
-import { shellArg } from './shell-arg.js';
 /**
  * Explain a slot that did not open, given the command that will now ask for the
  * recovery key anyway.
@@ -8,7 +7,7 @@ import { shellArg } from './shell-arg.js';
  * recovery key is typed. None of them is a dead end, which is the point: a
  * machine with no secure store is not a machine that cannot back up.
  */
-export function adviseOnSlot(result, ctx) {
+export function adviseOnSlot(result) {
     if (result.ok)
         return { tone: 'silent', lines: [] };
     switch (result.reason) {
@@ -45,7 +44,7 @@ export function adviseOnSlot(result, ctx) {
                 tone: 'note',
                 lines: [
                     'this machine has a secure store but it refused: ' + result.detail,
-                    `unlock it and run \`agmsg-cloud recovery setup ${shellArg(ctx.team)}\` again to keep a key`,
+                    `unlock it and run \`${setupCommand()}\` again to keep a key`,
                     'slot, so later backups do not ask for the recovery key. This run continues without one.',
                 ],
             };
@@ -93,24 +92,13 @@ export function adviseOnSlot(result, ctx) {
  * `recovery setup` once and this stops happening" would be a route that does
  * not exist on Windows or Linux.
  */
-export function adviseOnSlotForSilentFiling(result, ctx) {
+export function adviseOnSlotForSilentFiling(result) {
     if (result.ok)
         return { tone: 'silent', lines: [] };
-    // NAMED, and the argument is the point rather than a detail.
-    //
-    // `recovery setup` takes the team optionally now, and the no-argument form is
-    // the one its own documentation calls ordinary — which is why this printed it
-    // at first. But the broad form's success depends on every OTHER team the
-    // machine reports: one pass, no per-team isolation, so a `key.sh handoff`
-    // that fails for an unrelated team throws out of the loop and nothing is
-    // written. And if `remote.sh status --json` comes back short (agmsg#650) the
-    // target list can be empty, which refuses outright.
-    //
-    // Either way the person is sent to a command that can fail for a reason that
-    // has nothing to do with the team they just connected — and this is the one
-    // route they are given. Naming the team makes the remedy reach exactly the
-    // thing the sentence above it is about (raised in review).
-    const setup = `\`${setupCommand(ctx.team)}\``;
+    // The narrow form existed only while agmsg#650 could silently omit another
+    // team. That producer contract is now fail-closed, so recovery setup has one
+    // account-wide form everywhere it is printed (#182).
+    const setup = `\`${setupCommand()}\``;
     switch (result.reason) {
         case 'no-slot':
             return {

package/dist/src/vault-inventory.js

@@ -0,0 +1,118 @@
+/**
+ * Join the container against what the server calls each team.
+ *
+ * BOTH SETS COME OUT OF ONE RESPONSE. `listTeams` answers with the ids it
+ * returned and which of those carry a null name, so "in this org without a
+ * name" and "not in this org" are derived from the same read rather than from
+ * two lookups that could disagree. Deriving them separately is how two
+ * existence checks get mistaken for a relation.
+ */
+export function inventoryOf(container, names) {
+    const total = container.teams.length;
+    if (!names.asked)
+        return { namesKnown: false, total, entries: [...container.teams] };
+    const named = [];
+    const unnamed = [];
+    const unknown = [];
+    const ambiguous = [];
+    // The ids the org answered with — the set membership test for `unknown`.
+    const returned = new Set(names.teams.map((t) => t.teamId));
+    const byId = new Map(names.teams.map((t) => [t.teamId, t.teamName]));
+    // How many entries each id accounts for. Counted over the CONTAINER, not the
+    // response: the response cannot hold the same id twice, which is the whole
+    // reason a name from it cannot resolve a repeat here.
+    const perId = new Map();
+    for (const entry of container.teams) {
+        perId.set(entry.team_id, (perId.get(entry.team_id) ?? 0) + 1);
+    }
+    for (const entry of container.teams) {
+        // Before the name is consulted at all. An id the vault holds twice has no
+        // name that means one thing, so asking for one and then discarding it would
+        // be the same mistake with an extra step.
+        if ((perId.get(entry.team_id) ?? 0) > 1) {
+            ambiguous.push(entry);
+            continue;
+        }
+        if (!returned.has(entry.team_id)) {
+            unknown.push(entry);
+            continue;
+        }
+        const team = byId.get(entry.team_id);
+        // An empty string is not a name: it fails `agmsg_validate_team_name` ("must
+        // not be empty") and would reach the OSS side as a missing argument. It is
+        // the null case wearing a different type, so it lands in the same bucket.
+        if (team !== null && team !== undefined && team !== '')
+            named.push({ entry, team });
+        else
+            unnamed.push(entry);
+    }
+    // A NAME can repeat too, and a repeat is just as unplaceable. Team names are
+    // not unique on the server — `resolveTeamByName` refuses a name that matches
+    // more than one team for exactly this reason — so two entries with different
+    // ids can both come back called `alpha`. Only one local team can carry that
+    // name, and nothing in the response chooses between them: placing the first
+    // and letting the second collide is not a resolution, it is a race decided by
+    // the order the vault happens to store them in.
+    const perName = new Map();
+    for (const n of named)
+        perName.set(n.team, (perName.get(n.team) ?? 0) + 1);
+    const uniquelyNamed = [];
+    for (const n of named) {
+        if ((perName.get(n.team) ?? 0) > 1)
+            ambiguous.push(n.entry);
+        else
+            uniquelyNamed.push(n);
+    }
+    return { namesKnown: true, total, named: uniquelyNamed, unnamed, unknown, ambiguous };
+}
+/**
+ * The report, as lines.
+ *
+ * Built as data rather than written to stdout so a test can read it without a
+ * process, and so the one rule that matters is checkable: **the count of what
+ * could not be done is always printed when it is not zero**, with the ids.
+ */
+export function inventoryLines(inv, revision) {
+    const lines = [`opened the account vault, revision ${revision}`];
+    if (inv.total === 0) {
+        lines.push('it holds no team backups yet — `agmsg-cloud recovery setup` creates them');
+        return lines;
+    }
+    lines.push(`${inv.total} team backup(s) in it`);
+    if (!inv.namesKnown) {
+        // Every id, and no verdict about any of them. The entries are here; what
+        // failed is the question that would say which are placeable, and answering
+        // it anyway is how a network error becomes "your backups are unreachable".
+        lines.push('the server could not be asked for names, so none of these can be sorted yet:');
+        for (const entry of inv.entries)
+            lines.push(`  ${entry.team_id}`);
+        return lines;
+    }
+    for (const { team, entry } of inv.named) {
+        lines.push(`  ${team}  (${entry.team_id})`);
+    }
+    // Never folded together, and never folded into the count above. "4 of 6" that
+    // does not name the other two is the shape of a partial success printed as a
+    // success — and these two lists have different ways out, so a reader who is
+    // shown one line takes the worse of the two readings for all of them.
+    if (inv.unnamed.length > 0) {
+        lines.push(`${inv.unnamed.length} of ${inv.total} are in this org but the server has no name recorded` +
+            ` for them. If you know the name, it can be placed:`);
+        for (const entry of inv.unnamed)
+            lines.push(`  ${entry.team_id}`);
+    }
+    if (inv.ambiguous.length > 0) {
+        lines.push(`${inv.ambiguous.length} of ${inv.total} share a team id with another backup on a` +
+            ` different server, and the server's team list cannot say which name belongs to which:`);
+        for (const entry of inv.ambiguous) {
+            lines.push(`  ${entry.team_id}  on ${entry.server_instance_id}`);
+        }
+    }
+    if (inv.unknown.length > 0) {
+        lines.push(`${inv.unknown.length} of ${inv.total} did not appear in this org's teams at all —` +
+            ` this machine's credential cannot reach them:`);
+        for (const entry of inv.unknown)
+            lines.push(`  ${entry.team_id}`);
+    }
+    return lines;
+}