agmsg-cloud 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/src/api.js

@@ -324,7 +324,26 @@ export class CourierClient {
     // machine resolves the name here and pulls by id, rather than handing a
     // name to the data plane.
     async resolveTeamByName(name) {
-        const out = await this.call('GET', `/v1/edge/teams?name=${encodeURIComponent(name)}`);
+        return this.teams(`/v1/edge/teams?name=${encodeURIComponent(name)}`);
+    }
+    /**
+     * Every team in the caller's organization.
+     *
+     * The same endpoint without the `name` filter, so it discloses nothing the
+     * lookup above does not: the control plane scopes both to the caller's org
+     * (`WHERE org_id = $1`), which is the property that lets the name lookup live
+     * here instead of on the data plane.
+     *
+     * It exists so a failed lookup can tell two situations apart. "No team by
+     * that name" is the same answer whether nothing has ever been connected to
+     * this organization or the operator is signed in to the wrong one, and those
+     * need opposite next steps.
+     */
+    async listTeams() {
+        return this.teams('/v1/edge/teams');
+    }
+    async teams(path) {
+        const out = await this.call('GET', path);
         // A response this cannot read is not an answer about which teams exist,
         // and it must not be turned into one. `teams` must be PRESENT and an
         // array, with an empty array the only way to say "none" — the same rule

package/dist/src/commands/approve.js

@@ -360,7 +360,21 @@ args, deps = {}) {
             done();
             // Closed, not refunded: §4.1 keeps a success counted in the window.
             closeAttempt(scope, requestId, 'succeeded', undefined, env);
-            out(`approved; registered device ${device_id}\n`);
+            // The LABEL, not the id.
+            //
+            // `device_id` is a UUID the approver cannot use: no subcommand of this
+            // CLI accepts one (derived from index.ts — approve, connect, fetch,
+            // login, logout, pull, recovery, request, sync, watch, whoami, and none
+            // take a device). So it fails all three tests for reaching a person: it
+            // decides nothing for them, it cannot help them repair anything, and the
+            // label they just compared eight digits against is what actually names
+            // the machine they approved (#275 — the operator gets the minimum, the
+            // rest belongs in a log).
+            //
+            // Not routed to a log instead, because this CLI has no log to route it
+            // to. Building one for a single value would be the wrong size; when a
+            // second diagnostic needs a home, that is the moment to give it one.
+            out(`approved; "${start.label}" can now read this team\n`);
         }
         finally {
             rmSync(scratch, { recursive: true, force: true });

package/dist/src/commands/connect.js

@@ -6,7 +6,10 @@ 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 { adviseOnSlotForSilentFiling, renderSlotAdvice } from '../slot-advice.js';
+import { setupCommand } from '../recovery-key.js';
 import { shellArg } from '../shell-arg.js';
+import { fileTeamInVaultSilently } from '../vault-filing.js';
 function runInherit(command, args) {
     return new Promise((resolve, reject) => {
         // stdio inherited: `remote.sh connect` prints its own progress, and
@@ -120,9 +123,45 @@ export async function cmdConnect(config, opts) {
     // opening it — which needs the recovery key nobody has typed here. A
     // sentence about where the only copy is would be a guess whichever way it
     // went. The condition is named instead, and it is true in every case.
-    process.stdout.write(`\nBack these keys up: \`agmsg-cloud recovery setup ${shellArg(opts.team)}\`.\n` +
-        'Until a team is in your recovery vault, the only copies of its keys are on\n' +
-        'the machines that hold them; once it is there, the recovery key opens it again.\n' +
+    // Filed here rather than left to an instruction. The key was made moments
+    // ago by the step above, and until it is in the vault the only copies are on
+    // the machines holding them — a window that used to last until someone acted
+    // on a line that had already scrolled away (#181).
+    //
+    // Silently or not at all. `connect` does not ask for a recovery key: a
+    // command that stopped to collect one would be a ceremony, and the person
+    // running it did not come here for that. Both ways of being unable — no
+    // vault, no slot on this machine — fall back to naming the route, which is
+    // what this printed before.
+    //
+    // And the two are told apart, because "nothing happened, silently" is the
+    // outcome that leaves someone believing they are backed up.
+    const filing = await fileTeamInVaultSilently(config, new CourierClient(config), opts.team);
+    const teams = `${filing.filed ? filing.teamCount : 0} team${(filing.filed ? filing.teamCount : 0) === 1 ? '' : 's'}`;
+    const backup = filing.filed
+        ? filing.wrote
+            ? `Backed up: revision ${filing.revision}, ${teams} in this account's vault.\n` +
+                'Losing this machine no longer loses this team — the recovery key opens it again.'
+            : // Already there, with the same keys. Said as its own sentence rather
+                // than as a write, because claiming a revision this run did not produce
+                // is the same kind of false as claiming a backup that never happened —
+                // and a re-run of `connect` reaches here every time.
+                `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.
+                `Not backed up: this account has no recovery vault yet.\n` +
+                    `Run \`${setupCommand(opts.team)}\` 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();
+    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
         // between the machines after the yes — the sealed bundle, which is what
@@ -132,11 +171,33 @@ export async function cmdConnect(config, opts) {
         'You do not carry any value between the machines yourself: both screens show\n' +
         'eight digits and you check they are the same.\n');
     if (code !== 0) {
-        // Now that it is true, the operator can be told the failure needs nothing
-        // further — but only about the case where that is so. The error itself is
-        // still theirs to read; this does not summarise it.
-        process.stdout.write('Read the error above: if it was a uniqueness conflict, the team was already connected\n' +
-            'and there is nothing else to do.\n');
+        // THE CASE THIS USED TO NAME NO LONGER REACHES HERE.
+        //
+        // It said: "if it was a uniqueness conflict, the team was already connected
+        // and there is nothing else to do". That conflict was the OSS step refusing
+        // a second connect — `a team_id registers once ... not a transient error to
+        // retry` — and it is gone. Searched at the pin this repo carries
+        // (`92ddbe5`): no match in `scripts/`. It was removed by `8c2bd4b`, "a
+        // connect that already registered resumes instead of dead-ending", which is
+        // an ancestor of that pin. The script now adopts the registration and
+        // carries on, so a duplicate does not end non-zero at all.
+        //
+        // Leaving the sentence would have been worse than saying nothing: it asks
+        // the reader to look for a message that cannot appear, and the one it
+        // describes was the reassuring case, so a real failure would be read as the
+        // harmless one.
+        //
+        // Said as a property of this command rather than as a diagnosis of an error
+        // this side has not read — and only the part that was checked. Re-running
+        // adds nothing: the OSS step adopts a registration that is already there,
+        // and `bootstrapDevice` returns the existing device when the key matches
+        // (`devices.ts:309`). It is NOT "it will work": this same machine can be
+        // refused for reasons a second run cannot change, and the key having
+        // changed is refused rather than registered twice — which is why the
+        // sentence stops at "adds nothing".
+        process.stdout.write('Read the error above. Running connect again adds nothing that is already\n' +
+            'there: a registered team is adopted rather than refused, and this machine\n' +
+            'is registered once. It is worth doing if the error looks transient.\n');
     }
 }
 async function registerThisMachine(config, opts, machineName) {
@@ -192,7 +253,12 @@ async function registerThisMachine(config, opts, machineName) {
         // that is not the claimant never becomes one. Connect from here returns to
         // this same 403 forever.
         if (err instanceof CourierError && err.status === 403) {
-            throw new Error(await forbiddenAdvice(client, opts.team, pubkey));
+            // The id goes in, so the message can PRINT it. The release is asked for
+            // by team id, and the console shows teams by slug (`Connections.tsx:154`)
+            // — telling someone to go and find it is the placeholder problem this
+            // file already refuses elsewhere. It is in hand here; it is the value
+            // `bootstrapDevice` was just called with.
+            throw new Error(await forbiddenAdvice(client, opts.team, teamId, pubkey));
         }
         throw err;
     }
@@ -205,19 +271,30 @@ async function registerThisMachine(config, opts, machineName) {
  * account have a machine that could approve? Enrollment needs an approver, and
  * an approver is a registered device.
  *
- * The case with no approver is a real one and it has no way out today. That is
- * written plainly instead of offering a command that will wait forever, because
- * a person who is told there is no recovery stops spending time looking for one.
+ * The case with no approver has no way out THIS MACHINE CAN TAKE, which is not
+ * the same as no way out — and the message used to say the second one.
+ *
+ * There is a route: releasing the team's claim (`app/scripts/release-claim.ts`)
+ * frees the id, and a later connect claims it again. It is run by whoever
+ * operates the service, not by the person holding this terminal, and that is
+ * the decision rather than an omission — releases are rare enough to be worth a
+ * human checkpoint each time, and a self-service release would need an
+ * owner-authenticated mutation surface that does not exist. Both are recorded
+ * on #71, with the condition that would reopen the question.
+ *
+ * So the sentence to print is what to ASK FOR, not a command to run. A person
+ * told there is no recovery stops looking for one — which is right when there
+ * is none and expensive when there is, and #143 is the case where there was.
  *
- * WHY NOT BUILD A WAY BACK. Reassigning a team's claim to a live capability
- * would fix it, and it is a change nobody should make inside a bug fix: it
- * decides who may take over a team whose first machine is gone, and the obvious
- * answer — any live capability in the org — turns a revoked machine into "any
- * machine may become device-0 for that team", which is part of what revoking
- * was for. Named here so the next person who finds this message unhelpful
- * reaches the same question rather than the same guess.
+ * WHY NOT BUILD A WAY BACK HERE. Reassigning a team's claim to a live
+ * capability would also fix it, and it is a change nobody should make inside a
+ * bug fix: it decides who may take over a team whose first machine is gone, and
+ * the obvious answer — any live capability in the org — turns a revoked machine
+ * into "any machine may become device-0 for that team", which is part of what
+ * revoking was for. Named here so the next person who finds this message
+ * unhelpful reaches the same question rather than the same guess.
  */
-async function forbiddenAdvice(client, team, ownPubkey) {
+async function forbiddenAdvice(client, team, teamId, ownPubkey) {
     const head = `the server would not register this machine for '${team}'.\n\n` +
         'It is not the machine that first connected this team, and only that one can register\n' +
         'without an approver. That is recorded once and never moves, so running connect again\n' +
@@ -253,10 +330,19 @@ async function forbiddenAdvice(client, team, ownPubkey) {
     if (approvers === 0) {
         return (head +
             'There is also no OTHER machine on this account that could approve a request — and a\n' +
-            'machine cannot approve its own — so joining is not open either. THERE IS NO WAY TO\n' +
-            'RECOVER THIS TEAM FROM THIS ACCOUNT TODAY: the machine that claimed it can no longer\n' +
-            'register, and enrollment needs an approver that does not exist. Reported rather than\n' +
-            'dressed up as a command, so you do not spend the evening on one that cannot work.');
+            'machine cannot approve its own — so joining is not open either. NOTHING YOU CAN RUN\n' +
+            'FROM HERE RECOVERS THIS TEAM: the machine that claimed it can no longer register, and\n' +
+            'enrollment needs an approver that does not exist.\n\n' +
+            'What does recover it is releasing the team, which frees the id so a connect can claim\n' +
+            'it again. That is run by whoever operates this service, not from this terminal. Ask\n' +
+            'them to release this team, and say why:\n\n' +
+            `    team ${team}\n` +
+            `    id   ${teamId}\n\n` +
+            'Releasing DELETES EVERYTHING THIS SERVICE HOLDS FOR THE TEAM — its messages, its\n' +
+            'member list and their agent registrations, and its policy and identity history. That\n' +
+            'is the point of it: the id is freed for a fresh start, not handed over with its past.\n' +
+            'Your machines stay signed in and nothing on them is touched; it is this team on the\n' +
+            'service that goes. If any of it matters, say so before asking.');
     }
     return (head +
         'Join it from here instead — this account has another machine that can approve the\n' +

package/dist/src/commands/fetch.js

@@ -222,7 +222,25 @@ env = process.env) {
         // The choice is made from the VERIFIED matching set, never from the raw
         // queue: picking an unverified blob by position would not be identification.
         const { blob, file } = matches[0];
-        await unlockBundle(config.scriptsDir, args.team, file, expected);
+        const unlockSaid = await unlockBundle(config.scriptsDir, args.team, file, expected);
+        // Relayed HERE, before the ack, because it is already true here.
+        //
+        // The script has finished: the team is unlocked on this machine and its
+        // sync engine is running under a pid the script verified. Printing it after
+        // `ackBlob` meant a failed ack threw that away — the local half had
+        // succeeded, the operator was shown only the error, and the machine they
+        // were about to debug was already working. That is this issue's own defect
+        // one step later (raised in review).
+        //
+        // NOT verbatim, and the difference is worth naming rather than glossing:
+        // `trimEnd()` drops trailing whitespace and a single '\n' is re-appended.
+        // The body is untouched; only the tail is normalised. A script that says
+        // nothing prints nothing, because a blank line would read as an empty
+        // answer (raised in review — the comment said "verbatim", which is wider
+        // than what this does).
+        const said = (unlockSaid ?? '').trimEnd();
+        if (said !== '')
+            process.stdout.write(said + '\n');
         await client.ackBlob(blob.id);
         // Consumed only now, and the order is load-bearing.
         //
@@ -238,7 +256,23 @@ env = process.env) {
         clearAuthenticatedDigest(originOf(config.baseUrl), consumed.requestId, config.secret, devicePubkey, env);
         const others = blobs.length - 1;
         const duplicates = matches.length - 1;
-        process.stdout.write(`unlocked and acked the confirmed bundle` +
+        // What `remote.sh unlock` said — its body, with the trailing newline
+        // normalised to exactly one — and then what THIS command did.
+        //
+        // The script's line is the stronger one and it was being thrown away: it
+        // waits for the sync engine to report ready, checks the pidfile it recorded
+        // matches the process it started, checks that process is alive, and exits
+        // non-zero otherwise — so `engine running (pid N)` is a claim about a live
+        // pid, and it names the team.
+        //
+        // In its place this printed `unlocked and acked the confirmed bundle`,
+        // which names no object at all. Four lines later the operator was told to
+        // "unlock" — a DIFFERENT object, the team's history — with the same verb.
+        // Two objects, one word, and nothing on screen to tell them apart (#147).
+        //
+        // The ack is reported separately because it is this command's own act
+        // against the server, not something the script did.
+        process.stdout.write(`acked the confirmed bundle` +
             (others > 0 ? `; ${others} other bundle(s) left queued` : '') +
             (duplicates > 0 ? ` (${duplicates} of them carry the same digest)` : '') +
             '\n');

package/dist/src/commands/login.js

@@ -1,3 +1,4 @@
+import { SECRET_RE } from '../machine-id.js';
 import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../browser.js';
 import { isOrgAddress, originOf, readCredential, writeCredential } from '../credentials.js';
 import { settleMachineName, validateMachineName } from '../machine-name.js';
@@ -13,7 +14,11 @@ import { settleMachineName, validateMachineName } from '../machine-name.js';
 // out of the capability URL's last path segment, so a response that does not
 // carry the expected shape is refused rather than stored: a wrong value here
 // would be sent as this machine's Bearer credential on every later command.
-const SECRET_RE = /^agsy_[a-f0-9]{8}_[A-Za-z0-9_-]{43}$/;
+//
+// Imported, not restated. `machine-id.ts` reads the prefix out of the same
+// shape, and a second copy here would let the two drift: changing the mint in
+// one place would leave the other answering about a format that no longer
+// exists (raised in review).
 // The binary is `agmsg-cloud`, and the approval screen shows the name the
 // SERVER holds for this client id — so the id the CLI sends is what decides
 // whether the person sees "agmsg CLI" (a different program, which never does
@@ -58,6 +63,7 @@ export async function cmdLogin(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const now = opts.now ?? (() => Date.now());
+    const out = opts.out ?? ((text) => void process.stdout.write(text));
     const endpoint = (opts.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, '');
     // The flag, validated, before anything is asked. `settleMachineName` returns
     // it verbatim when it is given, so nothing below needs the prompt to know
@@ -68,7 +74,7 @@ export async function cmdLogin(opts) {
     // the thing it takes away is the moment the operator typed the destination —
     // so the destination is printed instead. Nobody should have to guess which
     // server their machine is about to be registered with.
-    process.stdout.write(`Connecting to ${new URL(endpoint).host}\n`);
+    out(`Connecting to ${new URL(endpoint).host}\n`);
     const post = async (path, body, bearer) => {
         try {
             return await fetchImpl(`${endpoint}${path}`, {
@@ -110,7 +116,7 @@ export async function cmdLogin(opts) {
     if (stored && (asked === undefined || stored.machineName === asked)) {
         const res = await post('/v1/device/activate', {}, stored.secret);
         if (res.ok) {
-            process.stdout.write(`Already signed in as machine "${stored.machineName}".\n`);
+            out(`Already signed in as machine "${stored.machineName}".\n`);
             return;
         }
         const code = await errorCode(res);
@@ -143,16 +149,32 @@ export async function cmdLogin(opts) {
         throw new Error(`could not start login: ${codeRes.status} ${code}`);
     }
     const grant = (await codeRes.json());
-    process.stdout.write(`\nOpen this page and check the code matches:\n\n`);
-    process.stdout.write(`  ${grant.verification_uri_complete}\n\n`);
-    process.stdout.write(`  code:    ${grant.user_code}\n`);
-    process.stdout.write(`  machine: ${machineName}\n\n`);
+    out(`\nOpen this page and check the code matches:\n\n`);
+    out(`  ${grant.verification_uri_complete}\n\n`);
+    out(`  code:    ${grant.user_code}\n`);
+    out(`  machine: ${machineName}\n\n`);
     // Armed, never awaited: an approval done from a phone, or from a URL typed by
     // hand, must still be noticed — so the poll below runs whether or not any key
     // is ever pressed. `disarm` is bound to every exit path, because a live stdin
     // listener would hold the process open after login has already finished.
     const opener = (opts.armOpener ?? armEnterToOpen)(grant.verification_uri_complete, endpoint);
-    process.stdout.write(`Waiting for approval — nothing is granted until you approve it.\n`);
+    // SAYS THAT THE BLOCKING IS THE DESIGN, and that the two lines above are
+    // already usable.
+    //
+    // An agent held the URL and the code for 42 seconds waiting for this command
+    // to return before relaying them — and it cannot return until someone
+    // approves, which nobody can do without seeing what it has already printed.
+    // The one step that needs a person was the step the person was locked out of
+    // (issue 279).
+    //
+    // The prompt handed to an agent carries four sentences about this. They are a
+    // description of behaviour this output can state itself, and prose in a
+    // prompt does not reach anyone who did not read that prompt — someone running
+    // the command by hand gets nothing.
+    out(`Waiting for approval — nothing is granted until you approve it.\n`);
+    out(`This command will not return until then. That is expected, not a failure:\n` +
+        `the page and the code above are ready to use now — open them, do not wait\n` +
+        `for this to finish.\n`);
     try {
         return await pollUntilDecided(grant, {
             post,
@@ -160,6 +182,7 @@ export async function cmdLogin(opts) {
             now,
             endpoint,
             armOpener: opts.armOpener ?? armEnterToOpen,
+            out,
         });
     }
     finally {
@@ -167,7 +190,7 @@ export async function cmdLogin(opts) {
     }
 }
 async function pollUntilDecided(grant, ctx) {
-    const { post, sleep, now, endpoint, armOpener } = ctx;
+    const { post, sleep, now, endpoint, armOpener, out } = ctx;
     // The poll is single-flight by construction: one loop, one request in flight.
     // A concurrent second poll on the same grant would revoke the credential the
     // first poll received.
@@ -193,7 +216,7 @@ async function pollUntilDecided(grant, ctx) {
             if (err instanceof Unreachable) {
                 // Said out loud rather than swallowed: an operator watching a long wait
                 // should see that contact was lost and regained, not silence.
-                process.stdout.write(`  (lost contact with the server, still waiting)\n`);
+                out(`  (lost contact with the server, still waiting)\n`);
                 continue;
             }
             throw err;
@@ -222,7 +245,7 @@ async function pollUntilDecided(grant, ctx) {
             if (!isOrgAddress(issued.org)) {
                 throw new Error('the server answered with an org address this build does not recognise — nothing was stored');
             }
-            return finish(issued, endpoint, post);
+            return finish(issued, endpoint, post, out);
         }
         const body = await errorBody(res);
         const code = body.code;
@@ -243,7 +266,9 @@ async function pollUntilDecided(grant, ctx) {
         throw new Error(explained ? `login stopped: ${explained}` : `login failed: ${res.status} ${code}`);
     }
 }
-async function finish(issued, endpoint, post) {
+async function finish(issued, endpoint, post, 
+/** The caller's sink, so every line this command prints goes one place. */
+out) {
     const secret = secretFromCapabilityUrl(issued.capability_url);
     // Durable write FIRST. If the process dies between here and activate, the
     // credential is on disk and the machine can be activated by running login
@@ -265,8 +290,8 @@ async function finish(issued, endpoint, post) {
         const code = await errorCode(res);
         throw new Error(`the credential was saved but could not be activated (${res.status} ${code}) — run login again`);
     }
-    process.stdout.write(`\nSigned in as machine "${issued.machine_name}".\n`);
-    process.stdout.write(`Its sync address is saved on this machine; no token to copy.\n`);
+    out(`\nSigned in as machine "${issued.machine_name}".\n`);
+    out(`Its sync address is saved on this machine; no token to copy.\n`);
 }
 async function errorCode(res) {
     return (await errorBody(res)).code;

package/dist/src/commands/pull.js

@@ -58,6 +58,57 @@ export async function cmdPull(config, opts) {
             'it asks a machine that already has the team, and the two of you compare eight digits.\n');
     }
 }
+/**
+ * The advice that follows "no team named X", chosen from what this
+ * organization actually holds.
+ *
+ * The observation and the advice are separated, because only the observation
+ * differs. **No answer this command can get establishes whether the team was
+ * connected anywhere** — the lookup is scoped to the caller's organization, so
+ * it cannot see the rest of the world at all:
+ *
+ *  - A populated organization does not mean the team was connected elsewhere.
+ *    An org holding `billing` and not `ops` is equally consistent with `ops`
+ *    never having been connected.
+ *  - An empty organization does not mean it was not. The case in #224 had it
+ *    connected into a different org, and that leaves this one empty.
+ *  - A list that could not be fetched says nothing in either direction.
+ *
+ * So the advice is one block, the same in all three, and names both
+ * possibilities as conditions. The original defect was a remedy stated as an
+ * instruction — "connect it from the machine that runs it" — which asserted the
+ * connect had not happened. Stating it unconditionally in ANY branch brings the
+ * defect back, which is why the regression pins the conditional form rather
+ * than the presence of new words.
+ *
+ * The list is printed in full. A "…and N more" would make the interesting case
+ * — the team IS here under a spelling the operator did not expect — the one
+ * most likely to be cut off, and an operator who cannot see it reads the
+ * message as saying it is not there. That is a deliberate trade against very
+ * large organizations, not an oversight.
+ */
+const WHERE_TO_LOOK = 'Where the team stands outside this organization is not visible from here.\n' +
+    'Check which account and organization this machine is signed in to, then:\n' +
+    '  - if another machine already connected it, sign in to the organization it\n' +
+    '    was connected into, or pass --team-id if you know the id;\n' +
+    '  - if it has not been connected anywhere yet, connect it from the machine\n' +
+    '    that runs it.';
+async function whyNot(client, team) {
+    let teams;
+    try {
+        teams = await client.listTeams();
+    }
+    catch {
+        return `This machine could not list the organization's teams, so what it holds is unknown.\n\n${WHERE_TO_LOOK}`;
+    }
+    if (teams.length === 0) {
+        return `This organization holds no teams, so nothing has been connected into it.\n\n${WHERE_TO_LOOK}`;
+    }
+    const named = teams.map((t) => `  ${t.teamName ?? '(unnamed)'}  ${t.teamId}`).join('\n');
+    return (`This organization holds ${teams.length === 1 ? '1 team' : `${teams.length} teams`}, and none of them is "${team}":\n\n` +
+        `${named}\n\n` +
+        `Check the spelling against that list.\n\n${WHERE_TO_LOOK}`);
+}
 async function resolveTeamId(config, opts) {
     const client = opts.client ?? new CourierClient(config);
     const matches = await client.resolveTeamByName(opts.team);
@@ -65,8 +116,15 @@ async function resolveTeamId(config, opts) {
         // Named as what it is: this org has no such team. The alternative reading
         // — that the team exists under someone else — is not ours to confirm or
         // deny, and the answer is the same either way.
-        throw new Error(`no team named "${opts.team}" in this organization.\n\n` +
-            'Connect it from the machine that runs it first, or pass --team-id if you have it.');
+        //
+        // What is ours to say is whether this organization holds ANY team, and the
+        // two cases need opposite moves. An empty organization means the connect
+        // has not happened; a populated one means it happened somewhere else, and
+        // "connect it from the machine that runs it" then points at work that is
+        // already done — which is what #224 reported. Asking the org for its own
+        // list adds no disclosure: it is the same org-scoped endpoint, without the
+        // filter.
+        throw new Error(`no team named "${opts.team}" in this organization.\n\n${await whyNot(client, opts.team)}`);
     }
     if (matches.length > 1) {
         // A name is not unique by construction, so this stops rather than picking.