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

package/dist/src/commands/vault.js

@@ -8,7 +8,7 @@ import { generateRecoveryKey, normalizeRecoveryKey, promptRecoveryKey, showRecov
 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 { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertTeam, } from '../vault-container.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
 // vault-protocol.ts for everything that talks to the server.
@@ -27,7 +27,10 @@ import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertT
 // omits the field name generation 1 by omission, and — worse — a slot saved
 // under a made-up 1 would be indistinguishable from a legitimate generation-1
 // slot once a re-issuance produced one.
-function slotAddress(identity, vaultId, generation) {
+// Exported for vault-filing.ts, which addresses the same slot from connect.
+// One derivation, because this decides WHICH slot is read: a second copy that
+// drifted would read a slot belonging to another vault or generation.
+export function slotAddress(identity, vaultId, generation) {
     return {
         vaultServiceId: identity.vaultServiceId,
         accountId: identity.accountId,
@@ -119,13 +122,6 @@ async function keepSlot(address, vdk) {
 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.
@@ -282,7 +278,13 @@ export async function cmdVaultPut(config, args) {
     // 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) => {
+    // `stranded` joins written/unchanged as a PARAMETER for the reason the two
+    // above are parameters: this function is defined before the loop fills any
+    // of them, and closing over a list that is still empty here prints a
+    // heading with nothing under it. The first version of this got that wrong
+    // in the other direction and listed the disconnected teams under
+    // "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
@@ -291,6 +293,12 @@ export async function cmdVaultPut(config, args) {
         const lines = [
             ...group('Backed up in this revision:', written),
             ...group('Already current, nothing to write:', unchanged),
+            // FIRST among the things that did not happen, and with the reason
+            // attached. This is the only group whose members are a contradiction in
+            // the store rather than a choice the operator made, so it is the one
+            // 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))),
@@ -321,34 +329,96 @@ export async function cmdVaultPut(config, args) {
         let next = container;
         const written = [];
         const unchanged = [];
+        // Recorded as connected by this machine, and not openable by it. Kept
+        // apart from `unseen` and `disconnected` because it is a third fact: the
+        // machine reported this team AND could not produce its keys, which is the
+        // store disagreeing with itself rather than a team the operator retired.
+        const couldNotOpen = [];
         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);
+            // ONE TEAM THIS MACHINE CANNOT OPEN DOES NOT DECIDE THE ACCOUNT (#276).
+            //
+            // The enumeration and this loop read DIFFERENT sources of truth, and
+            // that is the whole defect. `remote.sh status --json` reads only
+            // `teams/<team>/config`: a binding with a `connected_at` and no
+            // `disconnected_at` is reported active, and that read never opens
+            // `db/remote-sync/<team>.json`. The key handoff does. So a team whose
+            // binding record outlived its sync state arrives here looking ordinary
+            // and throws — measured on the 2026-08-11 walk, where a leftover named
+            // `oss-rc2` stopped the backup of four intact teams.
+            //
+            // The failure was TOTAL, and its blast radius was set by the oldest
+            // leftover on the machine rather than by anything the operator was
+            // doing. Skipping and naming is the answer, not refusing to start: this
+            // command already reports what it did not cover — `unseen`,
+            // `disconnected` — instead of refusing, for the same reason. A backup of
+            // four teams that says which fifth is missing leaves someone strictly
+            // better off than a backup of none; a backup of four that said nothing
+            // would not, which is why this is a report and not a silence.
+            //
+            // Any failure, not a matched message. Parsing `ENOENT` would name one
+            // shape of one version of one script, and the honest claim here is
+            // narrower: this machine could not produce this team's keys. The reason
+            // is carried through verbatim for whoever reads it.
+            let bundle;
+            try {
+                await keyHandoff(config.scriptsDir, target.team, bundleFile);
+                bundle = readFileSync(bundleFile);
+            }
+            catch (err) {
+                couldNotOpen.push({
+                    team: target.team,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
                 continue;
             }
-            next = upsertTeam(next, {
+            const keyIds = bundleKeyIds(bundle);
+            // The decision and the write are one call, in the container module, so
+            // `connect` cannot make the same decision differently (#181).
+            const result = upsertTeamIfMoved(next, {
                 server_instance_id: target.serverInstanceId,
                 team_id: target.teamId,
                 key_ids: keyIds,
                 bundle: bundle.toString('base64'),
             });
-            written.push(target.team);
+            next = result.container;
+            (result.written ? written : unchanged).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.
+        // NOTHING OPENED IS NOT A PARTIAL BACKUP. Skipping a team that cannot be
+        // opened is right while others can; when the whole set fails there is no
+        // backup to report, and writing here would store a container holding no
+        // teams — a recovery key that opens an empty vault, which reads as success
+        // and is worse than the abort this change replaced.
+        //
+        // Found by the test for this change, not by reading it back: the skip made
+        // the loop finish, and every path after the loop assumed finishing meant
+        // something had been filed.
+        if (written.length === 0 && unchanged.length === 0 && couldNotOpen.length > 0) {
+            process.stdout.write(coverage(written, unchanged, couldNotOpen));
+            throw new Error('no team on this machine could be opened, so nothing was backed up.\n' +
+                'Each team above is recorded here as connected while the state its keys ' +
+                'come from is missing.');
+        }
         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));
+            //
+            // AND IT NARROWS TO WHAT WAS OPENED. "nothing has new keys" is a claim
+            // over every team on the machine, but a team that could not be opened
+            // had its bundle and key epoch read zero times — whether it has new keys
+            // is not a thing this run knows. Unqualified, the line contradicts the
+            // coverage printed two statements later, which names that same team as
+            // one this run could not open (review P1-contract).
+            process.stdout.write(couldNotOpen.length > 0
+                ? `the teams this machine could open have no new keys; the ones below ` +
+                    `it could not open were not checked. Revision stays at ${version.revision}.\n`
+                : `already up to date — nothing has new keys. Revision stays at ${version.revision}.\n`);
+            process.stdout.write(coverage(written, unchanged, couldNotOpen));
             // 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.
@@ -389,7 +459,7 @@ export async function cmdVaultPut(config, args) {
         // (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));
+        process.stdout.write(coverage(written, unchanged, couldNotOpen));
         // 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
@@ -406,9 +476,28 @@ export async function cmdVaultPut(config, args) {
             // filing a key that opens nothing and trusting it for years. A re-run
             // mints a new one, which is correct — and only correct if they know to
             // discard this one.
+            // A REMEDY THAT IS PRINTED HAS TO END SOMEWHERE (#276).
+            //
+            // This used to say "running this command again will show you a new key",
+            // full stop. It does show a new key — and then fails in the same place,
+            // because re-running creates nothing that was missing. On the
+            // 2026-08-11 walk that sentence was followed each time, and each attempt
+            // burned a key and arrived back here, with the failure still advising
+            // the retry.
+            //
+            // 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.
             process.stdout.write('\nThe backup did NOT complete, so the recovery key above was never used\n' +
-                'and opens nothing. Discard it. Running this command again will show you\n' +
-                'a new key.\n\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');
         }
         throw err;
     }
@@ -419,7 +508,11 @@ export async function cmdVaultPut(config, args) {
 // The key epochs the bundle declares, for the entry's binding. This is the only
 // part of the bundle the cloud side reads: everything else is carried opaquely
 // and handed back to the OSS unlock path, so the bundle's format stays theirs.
-function bundleKeyIds(bundle) {
+// Exported alongside slotAddress, and for the same reason: vault-filing.ts
+// writes the same entry shape from connect, and a second reading of the
+// bundle that disagreed would record a binding to key epochs the bundle does
+// not declare.
+export function bundleKeyIds(bundle) {
     try {
         const parsed = JSON.parse(bundle.toString('utf8'));
         const ids = (parsed.identities ?? [])

package/dist/src/commands/whoami.js

@@ -0,0 +1,44 @@
+import { readCredential } from '../credentials.js';
+import { machinePrefix } from '../machine-id.js';
+export function whoami(env = process.env) {
+    // The ACTIVE credential, which is what every other command sends. Asking by
+    // origin would answer for a host this machine may not be using, and the
+    // question is "which machine am I", not "what do I have for X".
+    const credential = readCredential(null, env);
+    if (!credential)
+        return { signedIn: false };
+    return {
+        signedIn: true,
+        endpoint: credential.endpoint,
+        org: credential.org,
+        machineName: credential.machineName,
+        prefix: machinePrefix(credential.secret),
+    };
+}
+export function renderWhoami(found) {
+    if (!found.signedIn) {
+        return ('This machine is not signed in, so it is not one of the machines in any account yet.\n' +
+            'Run `agmsg-cloud login` first.\n');
+    }
+    const lines = [
+        `endpoint      ${found.endpoint}`,
+        `organization  ${found.org}`,
+        `machine name  ${found.machineName}`,
+    ];
+    if (found.prefix === null) {
+        // Said rather than omitted. A missing line reads as "this machine has no
+        // prefix", and the console will be showing one for it — so the person would
+        // be comparing against a row that does exist, with nothing to compare.
+        lines.push('', 'This version cannot read the prefix out of the stored credential: it is not', 'the shape this build knows. The machine still works — every other command', 'sends the secret as it is — but matching it against the console has to be', 'done another way. Upgrading `agmsg-cloud` is the thing to try first.');
+        return `${lines.join('\n')}\n`;
+    }
+    lines.push(`prefix        ${found.prefix}`, '', 
+    // Why the prefix is here at all, in the place someone reads it.
+    'The prefix is how you tell this machine apart from the others in the account:', 'it is the value shown beside the name on the console\'s machines screen, and', 'machine names are not unique. Match this one before revoking anything.', '', 
+    // Pre-empting the obvious worry about seeing part of a credential.
+    'It is not a secret — the console shows it to everyone in the organization.', 'The credential itself is the part that is not printed here, and never is.');
+    return `${lines.join('\n')}\n`;
+}
+export function cmdWhoami(env = process.env) {
+    process.stdout.write(renderWhoami(whoami(env)));
+}

package/dist/src/config.js

@@ -25,8 +25,36 @@ function fromEnv(env) {
 export function resolveScriptsDir(env = process.env) {
     return env.AGMSG_SCRIPTS_DIR ?? join(homedir(), '.agents', 'skills', 'agmsg', 'scripts');
 }
+/**
+ * THE credential decision. Every caller that needs to know whether this machine
+ * can act — and with what — goes through this one function.
+ *
+ * It is a function rather than a rule written twice because the two readers
+ * disagreed once already: preflight asked `readCredential` alone and reported a
+ * headless machine carrying AGMSG_CLOUD_ENDPOINT + AGMSG_CLOUD_SECRET as not
+ * signed in, refusing a machine that could run the command — #222's defect
+ * facing the other way (raised in review). The first repair merely copied this
+ * expression into both readers, which is the same arrangement with the
+ * divergence deferred: equal today, free to drift on the next edit (raised in
+ * review again). One body, so there is nothing to keep in step.
+ */
+function resolveCredential(env) {
+    return fromEnv(env) ?? readCredential(null, env);
+}
+/**
+ * Whether this machine has a credential to act with — `loadConfig`'s own
+ * question, asked of `loadConfig`'s own resolver, so preflight cannot hold a
+ * second opinion about a decision `loadConfig` already makes.
+ *
+ * A half-set pair still THROWS, exactly as it does for `loadConfig`: "endpoint
+ * set, secret missing" is a misconfiguration to report, not an absence to
+ * quietly call signed-out.
+ */
+export function hasCredential(env = process.env) {
+    return resolveCredential(env) !== null;
+}
 export function loadConfig(env = process.env) {
-    const resolved = fromEnv(env) ?? readCredential(null, env);
+    const resolved = resolveCredential(env);
     if (!resolved) {
         throw new Error('not signed in on this machine — run `agmsg-cloud login --endpoint <url>` first');
     }

package/dist/src/index.js

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

package/dist/src/machine-id.js

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

package/dist/src/oss.js

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

package/dist/src/preflight.js

@@ -1,5 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
+import { hasCredential } from './config.js';
 import { join } from 'node:path';
 import { platform } from 'node:process';
 // What `connect` needs before it starts, checked all at once.
@@ -150,10 +151,31 @@ function toolsFor(scripts) {
         python3: scripts.includes('remote.sh'),
     };
 }
-export function preflight(scriptsDir, needs) {
+export function preflight(scriptsDir, needs, env = process.env) {
     const { command, scripts } = needs;
     const requireConnect = needs.requireConnect ?? false;
     const requirements = [];
+    // BEING SIGNED IN IS A PREREQUISITE, so it is one of the things checked.
+    //
+    // It was not, and the result was a check that said "Everything connect needs
+    // is here" immediately before connect stopped for a missing sign-in (#222).
+    // A checklist that omits a requirement does not merely fail to help — it
+    // states that the requirement is met.
+    //
+    // Listed first because it is the one whose fix is a different command
+    // entirely, and because the others are about this machine's install while
+    // this one is about this machine's account.
+    requirements.push({
+        name: 'signed in',
+        // The resolver `loadConfig` uses, not a second opinion about the same
+        // question. `readCredential` alone reported a headless machine with
+        // AGMSG_CLOUD_ENDPOINT + AGMSG_CLOUD_SECRET as signed out — a checklist
+        // refusing a machine that CAN run the command, which is the defect this
+        // requirement exists to fix, facing the other way (raised in review).
+        ok: hasCredential(env),
+        why: `${command} talks to the hosted service as this machine, and this machine has no credential yet.`,
+        install: ['Sign in:             agmsg-cloud login'],
+    });
     // The scripts come first: without them nothing else matters, and the fix is
     // a different kind of thing (install agmsg, or point AGMSG_SCRIPTS_DIR at it)
     // than installing a binary.
@@ -205,6 +227,7 @@ export function preflight(scriptsDir, needs) {
         requirements,
         ok: requirements.every((r) => r.ok),
         command,
+        scriptsDir,
         agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
     };
 }
@@ -230,6 +253,16 @@ export function formatPreflight(result) {
     for (const r of result.requirements) {
         lines.push(`  ${r.ok ? '[x]' : '[ ]'} ${r.name}`);
     }
+    // THE RESOLVED DIRECTORY, IN FULL, ON ITS OWN LINE.
+    //
+    // It used to appear only inside a requirement's name — `agmsg with remote
+    // sync (in /very/long/path)` — where the walk's terminal cut it off. The
+    // operator could not see WHICH install had been checked, which is exactly
+    // the disagreement they were trying to diagnose (#222). A path is not a
+    // decoration on a label; it is the answer to "which one did you look at".
+    lines.push('');
+    lines.push(`  scripts directory:       ${result.scriptsDir}`);
+    lines.push(`  set AGMSG_SCRIPTS_DIR to check a different install.`);
     if (result.agmsgVersion !== null) {
         // Named as what it is. Calling it "agmsg 1.1.11" would invite the reader to
         // compare it with a release number, which is the thing it cannot be

package/dist/src/recovery-key.js

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