agmsg-cloud 0.1.0-rc.7 → 0.1.0

package/dist/src/api.js

@@ -1,4 +1,7 @@
 import { isCanonicalAgeRecipient } from '@agmsg-cloud/sas-core';
+import { DEFAULT_ENDPOINT } from './browser.js';
+import { originOf } from './credentials.js';
+import { shellArg } from './shell-arg.js';
 // Wire validation.
 //
 // Every response is checked here, at the boundary, rather than cast and trusted.
@@ -159,11 +162,81 @@ function requireTranscript(value) {
         throw new CourierError(200, 'malformed_enrollment');
     return value;
 }
+/**
+ * What a 401 from this client means, and why it can be said this precisely.
+ *
+ * `loadConfig` refuses before any request when this machine has no credential
+ * ("not signed in on this machine — run `agmsg-cloud login …` first"), so a
+ * request from here always carried a credential. A 401 is therefore never "you
+ * are not signed in": it is "the credential this machine used was refused".
+ *
+ * Telling that person to sign in names something they have already done, which
+ * is what #347 reported: `recovery restore` printed `courier request failed:
+ * 401 unauthenticated` and stopped there. `index.ts` prints `err.message`
+ * verbatim, so this string is the terminal output.
+ *
+ * WHICH CREDENTIAL, AND FOR WHICH ENDPOINT, both change the answer — and the
+ * first version of this got both wrong by writing one sentence for every case
+ * (review P1 on this PR):
+ *
+ *   - `loadConfig` prefers `AGMSG_CLOUD_ENDPOINT` + `AGMSG_CLOUD_SECRET` over
+ *     anything on disk. Calling that "this machine's stored credential" names a
+ *     file that does not exist, and `login` cannot fix it: it writes to disk,
+ *     the environment keeps winning, and the next command sends the same
+ *     refused secret. The remedy has to name the variables.
+ *   - bare `login` goes to `DEFAULT_ENDPOINT` (`commands/login.ts`), not to the
+ *     endpoint the refused credential belongs to. A message that offers
+ *     "minted for a different endpoint" as a cause and then drops the endpoint
+ *     from its own command contradicts itself.
+ *
+ * So the remedy is built where the source and the base URL are known, and every
+ * branch of it is a command that can actually be run.
+ *
+ * Bound to 401 alone. A 500 that advised re-authenticating would send people to
+ * `login` through an outage, where it is the one thing that cannot help.
+ *
+ * `login` itself does NOT go through this client — it talks to
+ * `/v1/device/activate` directly — so its own 401s cannot pick this up and tell
+ * someone mid-login to log in.
+ */
+export function refusedCredentialRemedy(input) {
+    // `originOf` throws on a value that is not a URL. A client built by hand in a
+    // test can hold one, and a remedy is not worth turning a 401 into a TypeError.
+    let origin;
+    try {
+        origin = originOf(input.baseUrl);
+    }
+    catch {
+        origin = input.baseUrl;
+    }
+    if (input.from === 'env') {
+        return (` — the credential in AGMSG_CLOUD_SECRET was refused by ${origin}.` +
+            ` \`agmsg-cloud login\` will NOT help while that pair is set: it writes to disk and` +
+            ` the environment still wins. Update or unset AGMSG_CLOUD_ENDPOINT and AGMSG_CLOUD_SECRET`);
+    }
+    // The endpoint is carried into the command whenever it is not the one `login`
+    // would pick on its own, quoted because a self-hosted origin is not always
+    // one shell word (`http://[::1]:5180` is a glob to zsh).
+    const flag = origin === originOf(DEFAULT_ENDPOINT) ? '' : ` --endpoint ${shellArg(origin)}`;
+    if (input.from === 'stored') {
+        return (` — this machine's stored credential for ${origin} was refused (revoked, or the machine was` +
+            ` removed). Run \`agmsg-cloud login${flag}\` again`);
+    }
+    // Source unknown: say what was refused and for where, and claim nothing about
+    // where the credential came from. An unknown source is exactly the case the
+    // first version got wrong by assuming one.
+    return ` — the credential this machine used for ${origin} was refused`;
+}
 export class CourierError extends Error {
     status;
     code;
-    constructor(status, code) {
-        super(`courier request failed: ${status} ${code}`);
+    constructor(status, code, 
+    /** Appended after the status and the code; empty for every failure that has none. */
+    remedy = '') {
+        // The status and the code stay in front. They are what makes a report
+        // actionable by someone who is not the person at the terminal, and a
+        // remedy that replaced them would trade one audience for the other.
+        super(`courier request failed: ${status} ${code}${remedy}`);
         this.status = status;
         this.code = code;
         this.name = 'CourierError';
@@ -173,10 +246,17 @@ export class CourierClient {
     baseUrl;
     secret;
     fetchImpl;
+    /**
+     * Where the secret came from, when the caller knows. `loadConfig` always
+     * knows; a client built by hand in a test usually does not, and the remedy
+     * says less rather than guessing (see `refusedCredentialRemedy`).
+     */
+    credentialFrom;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
         this.secret = opts.secret;
         this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.credentialFrom = opts.credentialFrom;
     }
     async call(method, path, body) {
         const res = await this.fetchImpl(`${this.baseUrl}${path}`, {
@@ -199,7 +279,9 @@ export class CourierClient {
             catch {
                 // no/'' JSON body — keep the generic code, never echo the raw response
             }
-            throw new CourierError(res.status, code);
+            throw new CourierError(res.status, code, res.status === 401
+                ? refusedCredentialRemedy({ baseUrl: this.baseUrl, from: this.credentialFrom })
+                : '');
         }
         return res.status === 200 || res.status === 201 ? res.json() : undefined;
     }

package/dist/src/commands/connect.js

@@ -6,6 +6,7 @@ import { originOf, readCredential } from '../credentials.js';
 import { generateDeviceIdentity, publicKeyOf, remoteTeamId } from '../oss.js';
 import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, formatPreflight, preflight } from '../preflight.js';
+import { runVersion } from '../self-install.js';
 import { adviseOnSlotForSilentFiling, renderSlotAdvice } from '../slot-advice.js';
 import { setupCommand } from '../recovery-key.js';
 import { shellArg } from '../shell-arg.js';
@@ -149,18 +150,18 @@ export async function cmdConnect(config, opts) {
                 `Already backed up: this team's keys were already in the vault at revision ${filing.revision},\n` +
                     `unchanged, so nothing new was stored. ${teams} in this account's vault.`
         : filing.reason === 'no-vault'
-            ? // NAMED, for the same reason as the four below: creating the vault and
-                // backing up THIS team is what the sentence above promises, and the
-                // broad form can refuse over a team that has nothing to do with it.
+            ? // Account-wide, now that agmsg#650 makes the broad enumeration
+                // fail-closed. Passing the team here taught the old per-team recovery
+                // model at exactly the moment a second team was about to be added.
                 `Not backed up: this account has no recovery vault yet.\n` +
-                    `Run \`${setupCommand(opts.team)}\` to make one — it shows a recovery key\n` +
+                    `Run \`${setupCommand()}\` to make one — it shows a recovery key\n` +
                     "once. Until then the only copies of this team's keys are on the machines\n" +
                     'that hold them.'
             : // Four ways of having no slot, four routes, and only one of them is
                 // "type the key once and this stops happening". Asked rather than
                 // written here, so a machine with no secure store is not sent after a
                 // fix that does not exist for it.
-                renderSlotAdvice(adviseOnSlotForSilentFiling(filing.slot, { team: opts.team })).trimEnd();
+                renderSlotAdvice(adviseOnSlotForSilentFiling(filing.slot)).trimEnd();
     process.stdout.write(`${backup}\n` +
         `\nTo add a second machine, run \`agmsg-cloud sync ${shellArg(opts.team)}\` there and answer here.\n` +
         // The subject is the operator, and it has to be. Something IS carried
@@ -351,8 +352,14 @@ async function forbiddenAdvice(client, team, teamId, ownPubkey) {
 }
 // Takes a scripts directory, not a CliConfig: this runs before a credential
 // exists, which is the point of a dry run.
-export function cmdConnectPreflight(scriptsDir) {
-    const checks = preflight(scriptsDir, NEEDS.connect);
+export function cmdConnectPreflight(scriptsDir, 
+/** Injected by the suite, so a check about tools does not spawn the tester's
+ *  own `agmsg-cloud` and wait on it. */
+run = runVersion) {
+    // THE REAL PROBE, HERE AND ONLY HERE (#341). Asking which `agmsg-cloud`
+    // answers means running it, and that belongs on the screen someone opens
+    // because they are confused — not in front of every connect that is working.
+    const checks = preflight(scriptsDir, NEEDS.connect, process.env, undefined, run);
     process.stdout.write(`\nChecking what connect needs:\n\n${formatPreflight(checks)}`);
     if (!checks.ok)
         throw new Error('prerequisites are missing');

package/dist/src/commands/login.js

@@ -1,7 +1,9 @@
 import { SECRET_RE } from '../machine-id.js';
 import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../browser.js';
-import { isOrgAddress, originOf, readCredential, writeCredential } from '../credentials.js';
+import { credentialsForOrigin, isOrgAddress, originOf, writeCredential } from '../credentials.js';
 import { settleMachineName, validateMachineName } from '../machine-name.js';
+import { resolveScriptsDir } from '../config.js';
+import { teamsBoundTo } from '../oss.js';
 // `login` — the device-authorization flow, from this machine's side.
 //
 // It is the one subcommand that runs with no credential, so it takes its
@@ -112,10 +114,38 @@ export async function cmdLogin(opts) {
     // rc.2 checked first. #169 moved the prompt to the top of the command to
     // reuse the name on both screens; nothing in it was about ordering, so
     // nothing looked at the ordering.
-    const stored = readCredential(originOf(endpoint), process.env);
+    //
+    // READ WITHOUT THE AMBIGUITY GUARD, and that is #399's own repair. This used
+    // to be `readCredential(originOf(endpoint))`, which fails closed when a host
+    // holds more than one credential — the exact state an rc.8 file is in, and
+    // the exact state this command exists to end. It threw here, before the
+    // grant, before the warning, before the replacing write, and told the person
+    // to run `logout` first. So "login replaces what is stored" held only for the
+    // single slots the new writer produces, and not for the machines already
+    // piled up. The guard was closed against its own remedy.
+    //
+    // Every other command keeps that guard. Acting on an ambiguous host is the
+    // defect; the one command about to collapse the ambiguity is the exemption.
+    const existing = credentialsForOrigin(originOf(endpoint), process.env);
+    // Only a host with exactly ONE credential can be re-activated: with two there
+    // is no answer to "which secret is this machine's", which is what made the
+    // reader throw in the first place. Two means a fresh grant, and the warning
+    // below says both are going.
+    const stored = existing.length === 1 ? existing[0] : null;
     if (stored && (asked === undefined || stored.machineName === asked)) {
         const res = await post('/v1/device/activate', {}, stored.secret);
         if (res.ok) {
+            // SAID THE WAY THE SUCCESS PATH SAYS IT. This line used to end with
+            // `in organization "<org address>"`, which put a server-minted address
+            // where the sentence had promised a name — the surrounding quotes make
+            // it read as one, and #329 begins with a reader asking what the value
+            // was. The path below that actually signs a machine in prints
+            // `Signed in as machine "<name>".` and no org, so the two answers to
+            // "am I signed in" now agree rather than differing by an identifier
+            // only one of them ever had.
+            //
+            // Not lost: `agmsg-cloud whoami` exists to answer which account this
+            // machine is in, and reads the same stored credential.
             out(`Already signed in as machine "${stored.machineName}".\n`);
             return;
         }
@@ -128,6 +158,93 @@ export async function cmdLogin(opts) {
             throw new Error(`a credential for ${originOf(endpoint)} is stored but could not be activated (${res.status} ${code}) — not starting a new login on top of it`);
         }
     }
+    // WHAT THIS RUN IS ABOUT TO DISPLACE, said before it happens (#399).
+    //
+    // Reaching this line with something stored means a fresh grant is opening on
+    // a host that already holds a credential, and a login now keeps ONE per
+    // service — so the stored one is going. The ruling is "delete the existing
+    // one", and the risk the ruling does not cover is doing that silently: a
+    // replace that drops a working setup without naming it is worse than a
+    // refusal that names it.
+    //
+    // SAID, NOT ASKED. A prompt is the obvious answer and it is the wrong one
+    // here: this command is handed to an AGENT by the onboarding screens, and an
+    // interactive confirm stalls a non-interactive caller with nobody to answer
+    // it. A `--force` flag has the mirror problem — the default path stays silent
+    // and the flag is the thing nobody types. So the disclosure goes in the
+    // output, at the point where there is still time to act on it: what follows
+    // is a browser round-trip that only completes when a person approves it, so
+    // reading this and stopping costs nothing.
+    //
+    // The second paragraph is the part that is not obvious. `logout` documents
+    // that it keeps the device key and the local team keys, and that holds here —
+    // history is not at stake. What IS at stake is subtler: a team's remote
+    // binding records the team id and the server instance, NOT which credential
+    // connected it. After this run, `readCredential(origin)` answers with the new
+    // org for a team that was connected under the old one — same host, different
+    // account, binding unchanged. Until now that was masked by the pile-up (both
+    // slots existed, so the resolver threw); with one credential per service there
+    // is nothing left to throw, so it has to be said.
+    // NO ORG ADDRESS ON THIS SCREEN, and the suite pins that. #329 took
+    // `stored.org` off the terminal here for a reason that applies twice over to a
+    // warning: it is a server-minted `org_<uuid>`, and dressing it as a name is
+    // how a reader ends up asking what the value was. A sentence about what you
+    // are losing is the worst place to put an identifier nobody can act on. The
+    // machine name is a name someone chose, and `whoami` is the command whose
+    // whole output is the answer to which account this is.
+    if (existing.length > 0) {
+        const origin = originOf(endpoint);
+        const names = existing.map((c) => `"${c.machineName}"`).join(', ');
+        out(existing.length === 1
+            ? `\nThis machine is already signed in to ${origin} as ${names}.\n`
+            : `\nThis machine holds ${existing.length} credentials for ${origin}, as ${names}, which an older agmsg-cloud allowed.\n`);
+        out(`Signing in again REPLACES ${existing.length === 1 ? 'that credential' : 'all of them'} — one per service is all this machine keeps.\n`);
+        // NAMED, not described. The decision recorded on #399 is that a
+        // replacement says which teams it lands on, and a general sentence about
+        // "teams under the current account" is not that — it also is not TRUE, in
+        // the precise sense: a binding records the host it was made against and no
+        // org at all, so "the outgoing account's teams" is a set this machine
+        // cannot compute. What it can compute is the teams bound to this SERVICE,
+        // which is the honest superset, and the wording says which one it is
+        // rather than implying the narrower claim.
+        let teams = null;
+        try {
+            const lookup = opts.teamsForOrigin ?? ((o) => teamsBoundTo(resolveScriptsDir(process.env), o));
+            teams = await lookup(origin);
+        }
+        catch {
+            // A sign-in must not fail because the team store could not be read — this
+            // command runs on machines with no teams and can run with no OSS install
+            // at all. But "could not read" is reported as itself: silently printing
+            // nothing would say "no teams are affected", which is the collapse of
+            // unknown into absent that this repository keeps paying for.
+            teams = null;
+        }
+        if (teams === null) {
+            out(`This machine's team list could not be read, so the teams this affects are not known here.\n`);
+        }
+        else {
+            // THREE STATES, not two, and the third is why `teamsBoundTo` returns two
+            // lists. A binding whose endpoint is missing or unparseable is neither in
+            // nor out: it may be bound to this host and this machine cannot tell. The
+            // first version dropped those silently, so a store with one unreadable
+            // binding printed "No team is bound", asserting an absence it had not
+            // measured — inside the change whose whole subject is not doing that.
+            if (teams.matched.length > 0) {
+                out(`Bound to ${origin}, and so affected: ${teams.matched.join(', ')}.\n`);
+            }
+            else if (teams.unreadable.length === 0) {
+                out(`No team on this machine is bound to ${origin}.\n`);
+            }
+            if (teams.unreadable.length > 0) {
+                out(`These teams could not be placed, so they may be affected too: ${teams.unreadable.join(', ')}.\n`);
+            }
+        }
+        out(`Those teams keep their keys and their history, but cloud commands for them will run as\n`);
+        out(`the new account. Reaching them as before means signing back in to the old one — run\n`);
+        out(`agmsg-cloud whoami first if you need to know which it is.\n`);
+        out(`Stop here if that is not what you meant.\n`);
+    }
     // Only now is the name needed: this run is opening a grant, so there really
     // is a machine to name.
     //

package/dist/src/commands/logout.js

@@ -41,6 +41,43 @@ export function logoutEndpoint(argv) {
     }
     return value;
 }
+/**
+ * What was signed out, in words the person who typed the command has.
+ *
+ * THIS LINE USED TO CARRY THE ORG ADDRESS, and the first thing its reader did
+ * with it was ask what it was (#329). The shape it came out in, with the
+ * machine's name replaced — this file ships to a public registry:
+ *
+ *     Signed out machine "laptop" from https://api.agmsg.cloud (org org_019fea9f-…).
+ *     Signed out machine "laptop" from https://api.agmsg.cloud (org org_019ff2a4-…).
+ *
+ * The rule from #275 is that a printed line earns its place by saying what
+ * happened, what to do next, or what is now at risk. An org address does none
+ * of the three HERE: no subcommand of this CLI takes one — derived from the
+ * usage block in `index.ts`, where the only identifier-shaped arguments are
+ * `pull --team-id` and `approve [request-id]`. So there is nothing the reader
+ * can do with it, and it is not theirs to recognise either.
+ *
+ * BUT THE COUNT IS NOT DECORATION, and dropping the address without it would
+ * have been worse than leaving it. Two credentials for two orgs on one host
+ * print the SAME machine name against the SAME origin — the address was the
+ * only thing telling those two lines apart. Removed on its own, the output
+ * above becomes one sentence printed twice, which reads as a bug rather than
+ * as "two accounts went". The number carries that fact and needs no glossary.
+ *
+ * WHERE A READABLE ORG GOES WHEN THERE IS ONE. #210 / #216 are deciding what a
+ * person-facing org identifier looks like; this is the line it belongs on when
+ * they land. Named here so that arrives as an edit rather than as a rediscovery.
+ */
+export function signedOutLine(removed, origin) {
+    // Distinct, because repeating one machine's name once per credential is the
+    // duplicate this function exists to avoid.
+    const names = [...new Set(removed.map((credential) => credential.machineName))].map((name) => `"${name}"`);
+    if (removed.length === 1)
+        return `Signed out machine ${names[0]} from ${origin}.\n`;
+    const machines = names.length === 1 ? `machine ${names[0]}` : `machines ${names.join(', ')}`;
+    return `Signed out ${removed.length} sign-ins from ${origin} (${machines}).\n`;
+}
 export function cmdLogout(opts = {}) {
     const env = opts.env ?? process.env;
     const out = opts.out ?? ((text) => void process.stdout.write(text));
@@ -58,13 +95,7 @@ export function cmdLogout(opts = {}) {
             out(`Cleared ${pending} pending enrollment record(s).\n`);
         return;
     }
-    // Named, not counted. The person signing out is entitled to know which
-    // identity just left this machine — one host can hold credentials for
-    // several orgs, and "signed out" without saying whose is how someone
-    // discovers later that the wrong one went.
-    for (const credential of removed) {
-        out(`Signed out machine "${credential.machineName}" from ${origin} (org ${credential.org}).\n`);
-    }
+    out(signedOutLine(removed, origin));
     if (pending > 0)
         out(`Cleared ${pending} pending enrollment record(s).\n`);
     // Said because the omission is the surprising part: someone who ran this to

package/dist/src/commands/request.js

@@ -6,9 +6,110 @@ import { recordAuthenticatedDigest } from '../authenticated-digest.js';
 import { CeremonyError, renderSasBlock, sasFromOpenedTranscript, waitForStatus } from '../ceremony.js';
 import { generateDeviceIdentity, publicKeyOf } from '../oss.js';
 import { originOf } from '../credentials.js';
+import { shellArg } from '../shell-arg.js';
 import { deviceIdentityPath } from '../paths.js';
 import { closeAttempt, consumeAttempt, readBudget, renderBudgetExhausted, renderBudgetWarning, requesterLedgerScope, } from '../ledger.js';
 import { attachRequestId, clearRecord, listResumableRequesterRecords, reserveRequesterNonce, } from '../pending.js';
+/**
+ * The one thing a long wait cannot say for itself: that it is the design.
+ *
+ * `login` learned this in #279 — an agent held a URL and a code for 42 seconds
+ * waiting for a blocking command to return, because nothing told it the block
+ * WAS the mechanism. These waits are longer: `login` waits for a browser the
+ * operator already has open, and these wait for a person on another machine.
+ *
+ * Written once and used at every wait, so the three cannot drift into saying
+ * different things about the same behaviour. What may be added to it is what
+ * stopping costs, and that is NOT the same at every wait — see below.
+ */
+function saysItBlocks() {
+    return '  This command will not return until then. That is expected, not a failure.\n';
+}
+/**
+ * What stopping costs, and it stops being free after the digits are shown.
+ *
+ * MEASURED, both of them, because the first version of this file asserted the
+ * resume in all three places and was wrong in one:
+ *
+ *   interrupted before the answer   the next run prints `resuming enrollment
+ *                                   <id>` and continues the same ceremony.
+ *                                   Budget unchanged: used:1 remaining:4.
+ *
+ *   interrupted at the LAST wait,   the row goes terminal while nothing is
+ *   and the approver then answers   watching. `GET /v1/enrollments` lists
+ *                                   NONTERMINAL rows only, so the stored
+ *                                   record matches nothing, the old attempt is
+ *                                   closed as failed, and the next run starts a
+ *                                   NEW ceremony. Measured: used:2 remaining:3
+ *                                   — one of five, spent.
+ *
+ * So the resume line belongs at the first two waits and is false at the third.
+ * Saying it there would promise a cheap retry for the one interruption that
+ * costs something.
+ */
+function stoppingIsCheap() {
+    return '  Leave it running — if you do stop it, run the same command again to resume.\n';
+}
+/**
+ * NOTHING HERE WARNS ABOUT A SECOND TERMINAL, and that is a refusal to guess
+ * rather than a finding.
+ *
+ * The console prompt says "do not start a second one in another terminal", and
+ * #344 asked whether that is true before repeating it. It was measured twice
+ * and the two measurements disagree:
+ *
+ *   an attempt opened under a commitment no run could plan
+ *                       -> `consumeAttempt` refuses with `attempt_already_open`
+ *                          — but that is not the branch a second terminal takes,
+ *                          because `request` looks for a resumable record first.
+ *                          A rigged input, and it agreed with the warning.
+ *
+ *   a first run interrupted mid-wait, then a second started
+ *                       -> once observed printing `resuming enrollment <id>`
+ *                          and carrying on at no cost; once observed starting a
+ *                          NEW ceremony instead. The two runs differed in their
+ *                          server double, and which difference decided it was
+ *                          not established.
+ *
+ * So this says nothing about second terminals in either direction. A warning
+ * has to be true to be worth a reader's attention, and so does a reassurance.
+ * What IS established is on `stoppingIsCheap` above: the cost of stopping, at
+ * each wait, measured.
+ */
+/**
+ * The line that hands the next step to the other machine.
+ *
+ * TWO HALVES OF ONE DEFECT, and this is the second (#329). The first wait used
+ * to print the enrollment id — which nobody types anywhere — and then name
+ * `agmsg-cloud approve` WITHOUT the argument it needs. So the value the reader
+ * could not use was on screen and the one they had to run was incomplete. In
+ * the two-machine walk the agent on the other side filled the gap by guessing
+ * the team, and reported its guess beside the id with nothing to say which of
+ * the two mattered.
+ *
+ * The team is threaded in from `sync`, which is the command that knows it.
+ * `request <label>` run on its own does NOT: the requester never typed a team,
+ * and no credential on that machine names one. That case gets `<team>` — a
+ * placeholder, which cannot be pasted by mistake, and which is still more than
+ * the bare command said.
+ *
+ * Quoted through `shellArg` because it is an argument of a line written to be
+ * pasted, on the same reasoning as every other printed command here.
+ *
+ * TWO BRANCHES RATHER THAN ONE ARGUMENT, and the sentence is repeated on
+ * purpose. Building `<team>`-or-quoted-team into a local first and
+ * interpolating that reads better and is what this function did until
+ * `check-printed-commands` refused it: the value at the point of use is not the
+ * value the declaration shows, so "it went through shellArg in one branch" is a
+ * claim the guard cannot verify. It is right to refuse it — that is #152's
+ * shape — so each literal carries a value that is safe where it stands.
+ */
+export function approveOnTheOtherMachine(team) {
+    const lead = '  The next move is on the other machine, where someone runs ';
+    return team === undefined
+        ? `${lead}\`agmsg-cloud approve <team>\`.\n`
+        : `${lead}\`agmsg-cloud approve ${shellArg(team)}\`.\n`;
+}
 export async function cmdRequest(config, args, deps = {}) {
     const out = deps.out ?? ((text) => void process.stdout.write(text));
     const writeErr = deps.err ?? ((text) => void process.stderr.write(text));
@@ -172,21 +273,42 @@ export async function cmdRequest(config, args, deps = {}) {
         });
         requestId = created.request_id;
         attachRequestId({ serverOrigin: config.baseUrl, commitmentHex: record.commitmentHex, requestId }, env);
-        out(`enrollment requested: ${requestId} (expires ${created.expires_at})\n`);
+        // THE ID IS NOT PRINTED, AND THE DEADLINE IS. #275's test, applied to the
+        // two halves of this line separately: the expiry says what is now at risk
+        // (this run has a window and it closes), and the request id says nothing
+        // the person at THIS terminal can use. `approve [request-id]` does take
+        // one — but `approve` runs on the OTHER machine, and the approver's own
+        // `watch` prints the id there already, inside the command to paste. So the
+        // value was shown to the one person in the ceremony who has no use for it.
+        //
+        // It is not lost: `attachRequestId` above wrote it to this machine's
+        // pending record a line earlier, which is where the resume path reads it
+        // from, and where it can be recovered if it is ever needed.
+        out(`enrollment requested (expires ${created.expires_at})\n`);
     }
     else {
-        out(`resuming enrollment ${requestId}\n`);
+        // Same value, same reason — and saying WHICH enrollment is resumed matters
+        // less than saying it is resumed rather than started, because that is the
+        // fact §4.1 makes expensive to get wrong (a second ceremony spends another
+        // of five attempts).
+        out('resuming the enrollment this machine already has open\n');
     }
     const done = () => clearRecord({ role: 'requester', serverOrigin: config.baseUrl, key: record.commitmentHex }, env);
     try {
-        out('waiting for an approver to commit...\n');
+        out('\nwaiting for an approver to commit...\n');
+        out(approveOnTheOtherMachine(args.team));
+        out(saysItBlocks());
+        out(stoppingIsCheap());
         await waitForStatus(client, requestId, 'both_committed', deps.waitOptions);
         // Safe to open now: the approver's contribution is fixed and cannot change.
         await client.submitOpening(requestId, {
             device_pubkey: pubkey,
             opening_nonce: record.nonceHex,
         });
-        out('waiting for the approver to open...\n');
+        out('\nwaiting for the approver to open...\n');
+        out('  Nothing to do here yet — the digits to compare appear when this returns.\n');
+        out(saysItBlocks());
+        out(stoppingIsCheap());
         const opened = await waitForStatus(client, requestId, 'opened', deps.waitOptions);
         // Derived here, from the two opened nonces. Nothing displayed below came
         // from the server as a code.
@@ -205,6 +327,22 @@ export async function cmdRequest(config, args, deps = {}) {
         // requirement that the requester counts failed and incomplete attempts, and
         // warns from the second failure, did nothing on this side. Wait for the
         // server to say which way it went.
+        // THE THIRD WAIT, and it said nothing at all — worse than the two the issue
+        // named, and the longest silence in the run.
+        //
+        // No line of its own, unlike the other two. What a reader has to do here is
+        // already on the screen directly above: `renderSasBlock` says the approving
+        // machine shows eight digits too, that they should check they are the same,
+        // and what each answer means. A copy of that here is the repetition #195
+        // removed from this very screen — a second copy of the one line that has to
+        // be read is how a reader learns to skim it. What was missing was not the
+        // instruction. It was that this blocks.
+        out('\nwaiting for the approver to answer...\n');
+        out(saysItBlocks());
+        // NOT `stoppingIsCheap()`. This is the one interruption that costs an
+        // attempt — see the note on that function for the measurement.
+        out('  Stopping here is the one that costs: if they answer while nothing is\n');
+        out('  watching, the next run starts over and spends one of five attempts.\n');
         const settled = await waitForStatus(client, requestId, 'consumed', deps.waitOptions);
         // What the eight digits authenticated, kept for `fetch`.
         //

package/dist/src/commands/sync.js

@@ -32,6 +32,39 @@ export async function cmdSync(config, opts) {
     const request = d.request ?? cmdRequest;
     const fetch = d.fetch ?? cmdFetch;
     const pull = d.pull ?? cmdPull;
+    const client = new CourierClient(config);
+    // BEFORE THE CEREMONY, because `request` spends one of five attempts before
+    // it posts the enrollment. The ceremony is org-scoped and cannot discover
+    // that the named team belongs to another org; leaving this to `pull` made a
+    // wrong-account run finish the human comparison, spend an attempt, and only
+    // then say the team was absent (#345).
+    //
+    // This lookup is scoped by the current credential on the control plane. A
+    // failure to answer is not absence, and ambiguity is not resolved here:
+    // neither state is permission to spend a ceremony on a guessed team.
+    let matches;
+    try {
+        matches = opts.teamId === undefined
+            ? await client.resolveTeamByName(opts.team)
+            : (await client.listTeams()).filter((team) => team.teamId === opts.teamId);
+    }
+    catch (err) {
+        out(`Not started: this account's organization could not be checked for "${opts.team}": ` +
+            `${err instanceof Error ? err.message : String(err)}\n` +
+            'No enrollment was started, so this costs none of your attempts.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (matches.length !== 1) {
+        out(matches.length === 0
+            ? `Not started: this account's organization has no team named "${opts.team}".\n`
+            : `Not started: this account's organization has more than one team named "${opts.team}".\n`);
+        out('Check `agmsg-cloud whoami`, then sign in to the organization that holds the team.\n');
+        out('No enrollment was started, so this costs none of your attempts.\n');
+        process.exitCode = 1;
+        return;
+    }
+    const resolvedTeamId = matches[0].teamId;
     // The approver sees this, and they are looking for a machine they recognise.
     // A hostname is what a person calls their laptop; a uuid is what they read
     // aloud wrongly.
@@ -62,7 +95,7 @@ export async function cmdSync(config, opts) {
     // join; failing the join over a failed courtesy check would be the refusal
     // this deliberately is not.
     try {
-        const existing = await new CourierClient(config).listDevices();
+        const existing = await client.listDevices();
         // THIS MACHINE'S OWN ROW IS NOT A CLASH WITH ITSELF.
         //
         // The comparison was on label alone, so a machine already on the account —
@@ -121,7 +154,18 @@ export async function cmdSync(config, opts) {
     // one that knows there is nothing to do: fetch and pull follow immediately
     // below. The decision is made HERE, once, rather than inferred inside each
     // step (raised in review).
-    const enrolled = await request(config, { label }, { nextStepsFromCaller: true });
+    // THE TEAM IS PASSED, and this is the only place that has it. `request` waits
+    // for someone on the key-holding machine to run `agmsg-cloud approve <team>`,
+    // and it named that command without its argument — so the person on the other
+    // end had to supply a value nothing on their screen had given them (#329). A
+    // `request <label>` typed on its own genuinely does not know the team and
+    // prints a placeholder; this path does know, so it says which one.
+    //
+    // Separate from `nextStepsFromCaller` below. That decides who tells the
+    // OPERATOR OF THIS MACHINE what to do when the ceremony ends, and the answer
+    // is this command. The line above is about the OTHER machine, whose next step
+    // is the same either way.
+    const enrolled = await request(config, { label, team: opts.team }, { nextStepsFromCaller: true });
     // NOTHING BELOW CAN SUCCEED WITHOUT IT, so a failed ceremony ends the run
     // here.
     //
@@ -162,9 +206,11 @@ export async function cmdSync(config, opts) {
     // It stayed hidden because the second machine in testing pointed at the first
     // machine's install, where the team was already present — so the second
     // machine's path had never actually been walked.
-    await pull(config, opts.teamId === undefined
-        ? { team: opts.team, nextStepsFromCaller: true }
-        : { team: opts.team, teamId: opts.teamId, nextStepsFromCaller: true });
+    await pull(config, {
+        team: opts.team,
+        teamId: resolvedTeamId,
+        nextStepsFromCaller: true,
+    });
     // And now the key, which opens what arrived above. Only reachable once the
     // server says the ceremony was approved — `request` waits for that, and
     // throws otherwise. The bundle is checked against the snapshot those digits