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

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/login.js

@@ -63,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
@@ -73,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}`, {
@@ -115,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}" in organization "${stored.org}".\n`);
             return;
         }
         const code = await errorCode(res);
@@ -148,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,
@@ -165,6 +182,7 @@ export async function cmdLogin(opts) {
             now,
             endpoint,
             armOpener: opts.armOpener ?? armEnterToOpen,
+            out,
         });
     }
     finally {
@@ -172,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.
@@ -198,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;
@@ -227,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;
@@ -248,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
@@ -270,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/request.js

@@ -9,6 +9,72 @@ import { originOf } from '../credentials.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.
+ */
 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));
@@ -179,14 +245,20 @@ export async function cmdRequest(config, args, deps = {}) {
     }
     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('  The next move is on the other machine, where someone runs `agmsg-cloud approve`.\n');
+        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 +277,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 —
@@ -87,13 +120,33 @@ export async function cmdSync(config, opts) {
         // this machine may join, and a scary line about an unrelated call would
         // compete with the instructions below.
     }
-    out('  On a machine that already has the team, run:\n\n');
-    // The real command, with the team quoted for a shell. A placeholder makes
-    // the reader do the substitution, and the whole point of this arc is to stop
-    // carrying values by hand between machines — an instruction that ends in
-    // `<team>` hands the work straight back (raised in review).
-    out(`      agmsg-cloud approve ${shellArg(opts.team)}\n\n`);
-    out('  Compare the eight digits on both screens before answering there.\n\n');
+    // PROSE, NOT A BLOCK TO COPY — and what changes is what this command claims
+    // at this moment, not what it knows (#307).
+    //
+    // Nothing here has established that the team exists, and nothing can. The
+    // local store is what `connect` and `fetch` fail closed on, and a second
+    // machine does not have one — that absence is the premise of `sync`. The name
+    // does not decide it either: `agmsg_validate_team_name` bars `.` `..`, `/`,
+    // `\`, a leading `-` and control characters, so `<team>` is a VALID team name.
+    // The ceremony below is scoped to the org rather than the team (#148). The one
+    // remaining source, asking the service by name, answers nothing for every team
+    // today (#250).
+    //
+    // So this is not a fix, and the issue stays open. What it removes is a
+    // misreading: an indented, copyable command reads as "this is the step", and
+    // when the person had not filled the placeholder it put a literal `'<team>'`
+    // on the other machine, quoted and ready to paste. As a sentence it reads as
+    // what it is — something to ask for, on a machine that has the team, which is
+    // a condition the reader can check and this process cannot.
+    //
+    // The command still goes through `shellArg`: the name reaching it is arbitrary
+    // text either way.
+    out(`  Ask a machine that already has "${opts.team}" to run ` +
+        `\`agmsg-cloud approve ${shellArg(opts.team)}\`, and compare the eight digits on ` +
+        'both screens before answering there.\n\n');
+    out(`  This machine has not confirmed that "${opts.team}" is on the service — it has no\n` +
+        '  way to, before the steps below. If that machine has no such team, stop here and\n' +
+        '  connect it there first.\n\n');
     // Everything the ceremony guarantees happens inside here: the commitment is
     // pinned before anything opens, nothing is sealed or uploaded until the
     // digits match, and this side refuses a transcript it cannot verify.
@@ -142,9 +195,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

package/dist/src/config.js

@@ -23,7 +23,48 @@ function fromEnv(env) {
 // `connect --preflight` is a dry run whose whole purpose is to be usable before
 // anything is set up, so it must not be refused for not being signed in.
 export function resolveScriptsDir(env = process.env) {
-    return env.AGMSG_SCRIPTS_DIR ?? join(homedir(), '.agents', 'skills', 'agmsg', 'scripts');
+    return scriptsDirChoice(env).dir;
+}
+/**
+ * The resolution, with its PROVENANCE — because the path alone does not answer
+ * the question an operator is actually asking (issue 282).
+ *
+ * An empty value is treated as unset. `??` passes the empty string through, so
+ * `export AGMSG_SCRIPTS_DIR=` resolved to `""` and every script path became a
+ * bare filename — measured, not supposed:
+ *
+ *     resolveScriptsDir({ AGMSG_SCRIPTS_DIR: '' })   ->  ""
+ *
+ * That is the shape someone reaches for when they are trying to undo the
+ * override, and it left them further from the default rather than back at it.
+ */
+export function scriptsDirChoice(env = process.env) {
+    const given = env.AGMSG_SCRIPTS_DIR;
+    if (given !== undefined && given !== '')
+        return { dir: given, from: 'env' };
+    return { dir: defaultScriptsDir(), from: 'default' };
+}
+/**
+ * The install used when `AGMSG_SCRIPTS_DIR` says nothing.
+ *
+ * Split out because it is also the answer to "what is the OTHER install"
+ * (issue 279), and a second copy of the path would be free to drift from the
+ * one the resolver uses — which is exactly the disagreement being reported.
+ *
+ * `home` is a PARAMETER, not `env.HOME`. The first version read
+ * `env.HOME ?? homedir()` and called it injectable-but-equivalent, on the
+ * grounds that `homedir()` reads `$HOME` on POSIX. That does not close: this
+ * CLI targets Windows, where a POSIX-compatible shell sets `HOME` to something
+ * like `/c/Users/x` while `homedir()` returns the native path — so the
+ * "equivalent" version would have moved the default install location for every
+ * Git Bash user (raised in review).
+ *
+ * Production never passes it. A seam a caller must opt into cannot change what
+ * anyone runs; an environment variable that production already has is not a
+ * seam at all.
+ */
+export function defaultScriptsDir(home = homedir()) {
+    return join(home, '.agents', 'skills', 'agmsg', 'scripts');
 }
 /**
  * THE credential decision. Every caller that needs to know whether this machine

package/dist/src/index.js

@@ -11,7 +11,7 @@ import { cmdPull } from './commands/pull.js';
 import { cmdRequest } from './commands/request.js';
 import { cmdVaultPut, cmdVaultRestore } from './commands/vault.js';
 import { cmdWatch } from './commands/watch.js';
-import { packageVersion } from './version.js';
+import { packageInstall } from './version.js';
 const USAGE = `agmsg-cloud — hosted agmsg from this machine
 
   login                        sign this machine in; approve it in your own browser
@@ -40,7 +40,8 @@ const USAGE = `agmsg-cloud — hosted agmsg from this machine
   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)
+  version                      the version of this CLI, and the directory it is
+                               running out of (also --version, -v)
                                the OSS scripts it drives are reported by
                                \`connect --preflight\`, which is a separate answer
 
@@ -104,7 +105,21 @@ async function main(argv) {
             // one it must assume someone will paste. Written without naming a
             // version: an example that has to be bumped is a second place to bump,
             // which is the reason this command reads the manifest at all.
-            process.stdout.write(`agmsg-cloud/${packageVersion()}\n`);
+            //
+            // The directory follows on its own line because the version alone does
+            // not answer the question people ask this command. `npm i -g agmsg-cloud`
+            // can succeed while a copy another package manager put earlier on PATH is
+            // what runs, and nothing about that is an error: both installs are valid
+            // and the shell picks one. That happened here, and the two defects being
+            // chased were already fixed in the copy that was NOT running. Choosing
+            // for the user would mean deciding their PATH; saying which one answered
+            // costs one line and leaves the choice where it was.
+            //
+            // A path, not a command: this line must not read as something to paste,
+            // which is why it is not shaped like an invocation.
+            const install = packageInstall();
+            process.stdout.write(`agmsg-cloud/${install.version}\n`);
+            process.stdout.write(`running from ${install.directory}\n`);
             return;
         }
         // Beside `version` for the same reason it sits there: both answer a

package/dist/src/preflight.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { hasCredential } from './config.js';
+import { defaultScriptsDir, hasCredential, scriptsDirChoice } from './config.js';
 import { join } from 'node:path';
 import { platform } from 'node:process';
 // What `connect` needs before it starts, checked all at once.
@@ -151,7 +151,17 @@ function toolsFor(scripts) {
         python3: scripts.includes('remote.sh'),
     };
 }
-export function preflight(scriptsDir, needs, env = process.env) {
+export function preflight(scriptsDir, needs, env = process.env, 
+/**
+ * The home directory the default install would be under.
+ *
+ * Only ever passed by a check that needs to put a second install somewhere it
+ * owns. It is a parameter rather than `env.HOME` because this CLI runs on
+ * Windows too, where a POSIX-compatible shell sets `HOME` to a path
+ * `homedir()` does not return — reading it would have moved the default
+ * install for every Git Bash user in exchange for a testable line.
+ */
+home) {
     const { command, scripts } = needs;
     const requireConnect = needs.requireConnect ?? false;
     const requirements = [];
@@ -229,8 +239,43 @@ export function preflight(scriptsDir, needs, env = process.env) {
         command,
         scriptsDir,
         agmsgVersion: canConnect ? installedVersion(scriptsDir) : null,
+        scriptsDirFrom: provenance(env, home),
+        otherInstalls: otherInstalls(scriptsDir, env, home),
     };
 }
+/**
+ * The install that exists at the location this command is NOT using.
+ *
+ * Only ever one, and only when `AGMSG_SCRIPTS_DIR` points somewhere other than
+ * the default: those are the two places `resolveScriptsDir` can name, so they
+ * are the two places worth reporting. `version.sh` is the marker rather than
+ * the directory itself — an empty `~/.agents/skills/agmsg/scripts` is not a
+ * second install, and calling it one would send someone to look at nothing.
+ */
+/**
+ * Which of the three states the resolution is in.
+ *
+ * Three, not two: the variable can be set AND point at the default, which is
+ * what someone has on the way to undoing an override. Collapsing it into "env"
+ * makes the output say "not the default location" about the default location.
+ */
+function provenance(env, home) {
+    const choice = scriptsDirChoice(env);
+    if (choice.from === 'default')
+        return 'default';
+    return choice.dir === defaultScriptsDir(home) ? 'env-at-default' : 'env';
+}
+function otherInstalls(scriptsDir, env, home) {
+    // Through the resolver's own accessor, so the two can never disagree about
+    // where "the default" is — a disagreement here would report the wrong
+    // directory as the one not in use.
+    const fallback = defaultScriptsDir(home);
+    if (scriptsDir === fallback)
+        return [];
+    if (!env.AGMSG_SCRIPTS_DIR)
+        return [];
+    return existsSync(join(fallback, 'version.sh')) ? [fallback] : [];
+}
 // The refusal in front of every command that shells out: one place decides how
 // a missing prerequisite reads, so it reads the same whichever command found
 // it.
@@ -262,7 +307,39 @@ export function formatPreflight(result) {
     // 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.`);
+    // WHAT PUT IT THERE, when something did.
+    //
+    // The hint below is advice to redirect the install. Printed while
+    // AGMSG_SCRIPTS_DIR is already set, it invites the reader to do the thing
+    // that is currently confusing them — "you could redirect this" when the truth
+    // is "this is redirected". So the two are alternatives, not a pair.
+    //
+    // Nothing extra when the default is in force: "this is the default" on every
+    // ordinary run is noise, and the sentence is only missing when something
+    // non-default is deciding.
+    if (result.scriptsDirFrom === 'env') {
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, not the default location.`);
+    }
+    else if (result.scriptsDirFrom === 'env-at-default') {
+        // The variable is set AND points at the default. Saying "not the default
+        // location" here would be false, and it is the state someone reaches while
+        // trying to undo an override — the one moment the sentence has to be exact.
+        lines.push(`  chosen by AGMSG_SCRIPTS_DIR, which points at the default location.`);
+    }
+    else {
+        lines.push(`  set AGMSG_SCRIPTS_DIR to check a different install.`);
+    }
+    // NAMES THE OTHER ONE, and says which of the two is in force.
+    //
+    // Without this the reader has to decide, and an agent that finds two installs
+    // stops and asks — the incident four lines of the handed-over prompt exist to
+    // prevent (issue 279). The answer is not a preference to be settled; it is
+    // already settled by the resolver, and this is it being said out loud.
+    for (const other of result.otherInstalls) {
+        lines.push('');
+        lines.push(`  another install is here:  ${other}`);
+        lines.push(`  it is NOT the one in use — AGMSG_SCRIPTS_DIR decides, and it points above.`);
+    }
     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
@@ -274,6 +351,15 @@ export function formatPreflight(result) {
     if (missing.length === 0) {
         lines.push('');
         lines.push(`Everything ${result.command} needs is here.`);
+        // SAYS THAT THIS IS THE CHECK.
+        //
+        // An agent told "make sure the prerequisites are met" checks them again
+        // unless something says not to — it has no way to know this output was the
+        // check rather than a summary of one. The prompt carries a sentence for
+        // exactly that ("do not check for tools yourself"), which is a property
+        // this output should have rather than a warning the reader must be given
+        // separately (issue 279).
+        lines.push(`This was the check. Nothing else needs testing before you run it.`);
         return `${lines.join('\n')}\n`;
     }
     for (const r of missing) {

package/dist/src/recovery-key.js

@@ -70,8 +70,8 @@ export function generateRecoveryKey() {
 // error rather than a silent drop, so a wrong key fails as a wrong key and not
 // as a mangled one.
 export function normalizeRecoveryKey(input) {
-    let cleaned = input
-        .trim()
+    const entered = input.trim();
+    let cleaned = entered
         .toUpperCase()
         .replace(/[\s-]/g, '');
     // The prefix is a label, not key material, and it is stripped by LENGTH
@@ -87,6 +87,17 @@ export function normalizeRecoveryKey(input) {
     if (cleaned.length === PREFIX_SYMBOLS + TOTAL_SYMBOLS && cleaned.startsWith('AGMSG')) {
         cleaned = cleaned.slice(PREFIX_SYMBOLS);
     }
+    // Locate a pasted label before diagnosing one character inside it. The
+    // prompt masks the input, so "unusable character: :" after a 50-character
+    // paste does not tell the operator where the colon was or what a key should
+    // look like. Length is the larger fact and can be checked without exposing
+    // the secret: the canonical form is 35 characters, while accepted spacing
+    // and grouping still reduce to exactly 25 key symbols (or 30 with AGMSG).
+    if (cleaned.length !== TOTAL_SYMBOLS) {
+        throw new Error(`that entry is ${entered.length} characters; a recovery key is 35 characters ` +
+            `in the form ${PREFIX}XXXXX-XXXXX-XXXXX-XXXXX-XXXXX ` +
+            `(${TOTAL_SYMBOLS} symbols without the prefix and separators)`);
+    }
     cleaned = cleaned
         .replace(/[IL]/g, '1')
         .replace(/O/g, '0')
@@ -95,9 +106,6 @@ export function normalizeRecoveryKey(input) {
         if (!ALPHABET.includes(ch))
             throw new Error(`recovery key contains an unusable character: ${ch}`);
     }
-    if (cleaned.length !== TOTAL_SYMBOLS) {
-        throw new Error(`recovery key must be ${TOTAL_SYMBOLS} symbols, got ${cleaned.length}`);
-    }
     // The check symbol, verified here rather than at the vault. Without it, a
     // mistyped key is indistinguishable from a wrong one until the AEAD refuses
     // it — which is at restore time, the moment there is no way back. Naming the

package/dist/src/slot-advice.js

@@ -14,12 +14,18 @@ export function adviseOnSlot(result, ctx) {
     switch (result.reason) {
         case 'no-slot':
             // The first backup on this machine, or the first after a re-issuance.
-            // Worth one line, because the next sentence asks for the recovery key and
-            // the person deserves to know why this time and not next time.
+            // Worth saying before the next sentence asks for the recovery key. Do
+            // not promise "once": knowing that the slot is absent is not knowing
+            // that this session may write its replacement. A headless macOS session
+            // can read the default keychain name and still have add-generic-password
+            // refused with errSecInteractionNotAllowed. That fact is learned only
+            // after the vault has opened, when saveDeviceSlot performs the write.
             return {
                 tone: 'note',
                 lines: [
-                    'this machine has no key slot for this vault yet, so the recovery key is needed once.',
+                    'this machine has no key slot for this vault yet, so the recovery key is needed now.',
+                    'After this succeeds, the CLI will try to keep a slot in the OS secure store. If this',
+                    'session cannot use that store, the recovery key will be needed every time.',
                 ],
             };
         case 'no-store':

package/dist/src/version.js

@@ -5,27 +5,23 @@ import { fileURLToPath } from 'node:url';
 // version — an identity, and the only thing that tells one package.json from
 // another while walking up a tree that may contain several.
 const PACKAGE_NAME = 'agmsg-cloud';
-// The version this build was published as.
-//
-// Read from the package's own `package.json` at runtime rather than baked into
-// a constant, because a constant is a second place to update and the one that
-// gets forgotten: a build that says the wrong version is worse than one that
-// says none, since the answer looks authoritative either way. npm always
-// includes package.json in a tarball, so it is there for a published install.
-//
-// Found by walking UP from this module rather than by a fixed relative path,
-// because the depth differs between the two places this file runs from:
-// `src/version.ts` sits one level under the package root, `dist/src/version.js`
-// sits two. A path correct in one is wrong in the other, and the one that would
-// be wrong is the published one.
-//
-// The walk answers only from a manifest that NAMES this package. Without that
-// check the first non-empty version above the module wins, and the installs
-// most likely to hit it are the broken ones — a package.json missing or
-// stripped of its version is exactly when a monorepo root, an npx cache entry,
-// or a parent workspace supplies its own. Reporting a stranger's version is the
-// failure this command exists to prevent, wearing the shape of a success.
-export function packageVersion(moduleUrl = import.meta.url) {
+/**
+ * The install this process is running out of: its version AND where it is.
+ *
+ * Both come from ONE walk, and that is the point rather than a convenience.
+ * `which agmsg-cloud` answers from PATH and a manifest answers from the module
+ * graph; when two package managers have both installed this tool, those are two
+ * different questions with two different answers, and pairing them would report
+ * a directory that need not be where the version came from. The directory
+ * returned here is the one whose `package.json` supplied the version, so the
+ * two cannot disagree.
+ *
+ * Node resolves a module's realpath before loading it, so a bin symlink — the
+ * usual shape of a global install — has already been followed by the time
+ * `import.meta.url` exists. What comes back is the store directory, which is
+ * the part that tells a pnpm global install from an npm one.
+ */
+export function packageInstall(moduleUrl = import.meta.url) {
     let dir = dirname(fileURLToPath(moduleUrl));
     const { root } = parse(dir);
     for (;;) {
@@ -41,7 +37,7 @@ export function packageVersion(moduleUrl = import.meta.url) {
         if (manifest?.name === PACKAGE_NAME) {
             const version = manifest.version;
             if (typeof version === 'string' && version !== '')
-                return version;
+                return { version, directory: dir };
             // Fail closed. This IS the package and it cannot say what it is; climbing
             // past would hand the question to whatever sits above, which is how a
             // broken install comes to announce a stranger's version.
@@ -55,3 +51,6 @@ export function packageVersion(moduleUrl = import.meta.url) {
     // guessed — see the note above.
     throw new Error(`cannot determine the installed version: no ${PACKAGE_NAME} package.json above this module`);
 }
+export function packageVersion(moduleUrl = import.meta.url) {
+    return packageInstall(moduleUrl).version;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.8",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,7 +33,9 @@
     "pretypecheck": "pnpm run build:deps",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsx scripts/check-printed-commands.ts && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
-    "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts"
+    "prepack": "pnpm run build && tsx scripts/check-dist-is-current.ts && tsx scripts/check-readme-commands.ts && tsx scripts/check-handles.ts",
+    "verify:published": "tsx scripts/verify-published.ts",
+    "verify:shown-install": "tsx scripts/verify-shown-install.ts"
   },
   "dependencies": {
     "@agmsg-cloud/sas-core": "workspace:*",