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

package/dist/src/commands/request.js

@@ -9,22 +9,6 @@ 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';
-// (c, part 1) B asks to be added.
-//
-// The order below is the protocol, not a style choice:
-//
-//   1. commit to (device key, nonce) and PERSIST the nonce
-//   2. post only the commitment digest
-//   3. wait for the approver's commitment to be fixed
-//   4. only then reveal the key and the nonce
-//   5. wait for the approver to open, and derive the code locally
-//
-// Steps 3 and 4 are what stop the other side choosing its contribution after
-// learning ours. Doing 4 before 3 would leave a request whose code the server
-// could steer, and the human comparison would confirm nothing.
-//
-// The private key never leaves this machine; only the public recipient is sent,
-// and not until step 4.
 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));
@@ -47,11 +31,39 @@ export async function cmdRequest(config, args, deps = {}) {
     // paid for would charge the same guess twice and let a crash loop exhaust the
     // budget without a single comparison.
     const scope = requesterLedgerScope(config.baseUrl, pubkey);
-    // A record without an id may still have landed: the row can exist on the
-    // server while the response was lost. Ask, using the only handle available —
-    // the commitment. Dropping these was what left the ledger's open attempt
-    // blocking every retry with nothing able to clear it.
-    if (record && !requestId) {
+    // ASKED FOR EVERY STORED RECORD, INCLUDING ONE THAT ALREADY HAS AN ID.
+    //
+    // Two different questions, one answer:
+    //
+    //   no id    did it land at all? The row can exist while the response was
+    //            lost, and the commitment is the only handle left.
+    //   with id  is it still live? Nothing about the id says so.
+    //
+    // This used to run only for the first. A record with an id was trusted
+    // however old it was, and the first thing the run did with it was
+    // `waitForStatus`, which polls for PROGRESS — so a long-dead enrollment was
+    // resumed, waited on, and then reported expired. That is the walkthrough
+    // sequence in #143: `resuming enrollment <id>` followed by `<id> is expired`.
+    //
+    // One list answers both, because `GET /v1/enrollments` is scoped to
+    // `status = ANY(NONTERMINAL) AND expires_at > now()`
+    // (`app/src/handoff/enrollment.ts:306`) — an expired row is absent from it
+    // even while its status still reads non-terminal. So "not in the list" already
+    // means "cannot be resumed", and the branch below already does the right
+    // thing with that: it closes the attempt, drops the record, and falls through
+    // to starting a fresh ceremony in this same run.
+    //
+    // AND THE LIST IS THE ONLY PLACE THAT ANSWERS IT. Reading the id instead would
+    // not do: `expireStale` rolls a stale row over on touch, and its callers are
+    // the create and claim paths, so a read returns the status the ceremony left
+    // behind and says nothing about the deadline. (That the walkthrough saw `<id>
+    // is expired` at all means something else had already touched it.) Pinned on
+    // the server side in `app/test/handoff-enrollment.test.ts`, because a change
+    // there would otherwise leave every test here green.
+    //
+    // The cost is one extra request per resume. What it buys is that the run
+    // either resumes something that can still finish, or starts one that can.
+    if (record) {
         // The list must SUCCEED before its emptiness means anything.
         //
         // Swallowing the error and treating it as "no live requests" turned a
@@ -64,12 +76,20 @@ export async function cmdRequest(config, args, deps = {}) {
             mine = await client.listEnrollments();
         }
         catch (err) {
-            writeErr('cannot tell whether the earlier request reached the server: ' +
+            // The two cases have different unknowns and the sentence says which one
+            // it is. With no id, whether the request ever landed is open; with an id
+            // it landed and what is open is whether it can still finish. Saying "did
+            // it reach the server" to someone holding an id describes a doubt they do
+            // not have, and the remedy is the same either way — which is what makes
+            // the wrong half safe to notice and cheap to fix.
+            writeErr((requestId
+                ? `cannot tell whether enrollment ${requestId} is still live: `
+                : 'cannot tell whether the earlier request reached the server: ') +
                 `${err instanceof Error ? err.message : String(err)}\n` +
                 '  Nothing has been changed — the attempt and its nonce are kept so a\n' +
                 '  later run can finish it. Try again when the server is reachable.\n');
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         const match = mine.filter((e) => e.commitment === record.commitmentHex);
         if (match.length === 1) {
@@ -90,7 +110,7 @@ export async function cmdRequest(config, args, deps = {}) {
             writeErr('the server reports more than one live request for this commitment; ' +
                 'refusing to guess which one is yours\n');
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
     }
     if (!record || !requestId) {
@@ -116,13 +136,13 @@ export async function cmdRequest(config, args, deps = {}) {
         if (before.remaining === 0) {
             writeErr(renderBudgetExhausted(before));
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         const blocked = await keyAlreadySpokenFor(client, pubkey);
         if (blocked) {
             writeErr(blocked);
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         const { commitmentHex: plannedCommitment, openingNonce: plannedNonce } = createSasCommitment(pubkey);
         const charged = consumeAttempt(scope, plannedCommitment, env);
@@ -135,7 +155,7 @@ export async function cmdRequest(config, args, deps = {}) {
                     '  command again to resume it rather than starting a second one.\n\n');
             }
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         out(renderBudgetWarning(charged.budget));
         // Persisted BEFORE the digest is posted. A crash after the post but before
@@ -220,6 +240,7 @@ export async function cmdRequest(config, args, deps = {}) {
         // the production walkthrough).
         out(`  Added.${nextStepsAreOurs ? ' Fetch the bundle with `agmsg-cloud fetch <team>`.' : ''} (${settled.status})\n`);
         done();
+        return 'enrolled';
     }
     catch (err) {
         if (err instanceof CeremonyError) {
@@ -227,19 +248,31 @@ export async function cmdRequest(config, args, deps = {}) {
             // A timeout leaves it, so the next run resumes instead of spending another
             // attempt on a request that is still live.
             if (err.reason === 'timed_out') {
-                // The ceremony may still be live; the next run resumes the same one and
-                // is not charged again.
+                // "May still be live" was printed as though it were "is still live".
+                //
+                // The wait has a five-minute deadline and an enrollment's window can
+                // close inside it — and expiry alone does not move the status, so the
+                // poll ends as "did not reach … in time" for a row that is expired and
+                // untouched. Both halves of the old sentence were then false: the next
+                // run does not resume it, and the new ceremony it starts does cost an
+                // attempt. Someone following the remedy spent one having been told it
+                // was free (#258).
+                //
+                // Asked of the same list the resume path asks, which is scoped to
+                // `status = ANY(NONTERMINAL) AND expires_at > now()` — so presence
+                // there IS resumability, and there is no second definition to keep in
+                // step.
                 writeErr(`enrollment did not complete: ${err.message}\n`);
-                writeErr('  Run the same command again to resume it; this costs no further attempt.\n');
+                writeErr(await resumeAdvice(client, record.commitmentHex));
                 process.exitCode = 1;
-                return;
+                return 'not_enrolled';
             }
             done();
             closeAttempt(scope, record.commitmentHex, 'failed', err.reason, env);
             writeErr(renderBudgetWarning(readBudget(scope, env)));
             writeErr(`enrollment did not complete: ${err.message}\n`);
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         // The two ways this machine's key cannot become a device on this account.
         //
@@ -257,7 +290,7 @@ export async function cmdRequest(config, args, deps = {}) {
             writeErr(renderBudgetWarning(readBudget(scope, env)));
             writeErr(await renderKeyRefusal(err.code, client, pubkey));
             process.exitCode = 1;
-            return;
+            return 'not_enrolled';
         }
         throw err;
     }
@@ -287,6 +320,37 @@ const NOTHING_COMPARED = '  No digits were shown and no bundle was sent.\n';
  * about ownership, and reading silence as "none of these are yours" would
  * refuse every ordinary rejoin.
  */
+/**
+ * What to tell someone whose wait ran out — after asking whether the thing they
+ * would be resuming still exists.
+ *
+ * Three answers, because there are three states and only one of them is the one
+ * the message used to assume. Saying nothing about the cost is not an option
+ * either: the whole defect was a person spending an attempt they had been told
+ * was free, and a sentence that simply omits the price leaves them guessing at
+ * the same moment.
+ */
+export async function resumeAdvice(client, commitmentHex) {
+    let live;
+    try {
+        live = await client.listEnrollments();
+    }
+    catch (err) {
+        // Unknown, said as unknown. Guessing "still live" is the bug being fixed;
+        // guessing "gone" would tell someone their attempt is spent when it may
+        // not be.
+        return (`  Could not check whether it is still live: ${err instanceof Error ? err.message : String(err)}\n` +
+            '  Nothing has been changed. Run the command again when the server is reachable:\n' +
+            '  if the enrollment is still live it resumes at no further cost, and if it is\n' +
+            '  not, that run starts a new ceremony and costs another attempt.\n');
+    }
+    if (live.some((e) => e.commitment === commitmentHex)) {
+        return '  Run the same command again to resume it; this costs no further attempt.\n';
+    }
+    return ('  This attempt is over: the enrollment is no longer live on the server, so it\n' +
+        '  cannot be resumed. Running the command again starts a NEW ceremony, which\n' +
+        '  costs another attempt.\n');
+}
 async function keyAlreadySpokenFor(client, pubkey) {
     let devices;
     try {

package/dist/src/commands/sync.js

@@ -87,13 +87,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.
@@ -101,7 +121,27 @@ 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).
-    await request(config, { label }, { nextStepsFromCaller: true });
+    const enrolled = await request(config, { label }, { nextStepsFromCaller: true });
+    // NOTHING BELOW CAN SUCCEED WITHOUT IT, so a failed ceremony ends the run
+    // here.
+    //
+    // It used to continue. `cmdRequest` reports failure by setting
+    // `process.exitCode` and returning normally — it does not throw — and this
+    // line ignored the return value, so `pull` ran next and resolved the team by
+    // name against an account this machine had not joined. What the operator was
+    // left holding was `no team named "<team>" in this organization`: true, and
+    // not the reason anything failed. The enrollment message had scrolled past
+    // two steps earlier.
+    //
+    // Nothing is printed here. `request` has already said what happened and what
+    // to do about it, in the words that fit the case it hit; a summary from this
+    // side would either repeat it or, worse, generalise over cases it cannot
+    // tell apart.
+    //
+    // Compared against the success value rather than the failure one, so a
+    // future outcome that is neither stops the run as well.
+    if (enrolled !== 'enrolled')
+        return;
     // PULL BEFORE FETCH, and the old order was the wrong way round.
     //
     // The comment that used to sit below said the messages "needed the key that

package/dist/src/commands/vault.js

@@ -8,7 +8,7 @@ import { generateRecoveryKey, normalizeRecoveryKey, promptRecoveryKey, showRecov
 import { appendVaultVersionWithVdk, createVault, openVaultWithVdk, readAccountVault, vdkFromRecoveryKey, } from '../vault-protocol.js';
 import { openDeviceSlot, saveDeviceSlot } from '../device-slot.js';
 import { adviseOnSlot, renderSlotAdvice } from '../slot-advice.js';
-import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertTeam, } from '../vault-container.js';
+import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertTeamIfMoved, } from '../vault-container.js';
 // The two recovery commands: resolve the team, obtain the bundle from the OSS
 // side, get the recovery key from the terminal, and hand off to
 // vault-protocol.ts for everything that talks to the server.
@@ -27,7 +27,10 @@ import { emptyContainer, parseContainer, selectTeam, serializeContainer, upsertT
 // omits the field name generation 1 by omission, and — worse — a slot saved
 // under a made-up 1 would be indistinguishable from a legitimate generation-1
 // slot once a re-issuance produced one.
-function slotAddress(identity, vaultId, generation) {
+// Exported for vault-filing.ts, which addresses the same slot from connect.
+// One derivation, because this decides WHICH slot is read: a second copy that
+// drifted would read a slot belonging to another vault or generation.
+export function slotAddress(identity, vaultId, generation) {
     return {
         vaultServiceId: identity.vaultServiceId,
         accountId: identity.accountId,
@@ -119,13 +122,6 @@ async function keepSlot(address, vdk) {
 function vaultTeamKey(serverInstanceId, teamId) {
     return JSON.stringify([serverInstanceId, teamId]);
 }
-function sameEpochs(a, b) {
-    if (a.length !== b.length)
-        return false;
-    const left = [...a].sort();
-    const right = [...b].sort();
-    return left.every((v, i) => v === right[i]);
-}
 /**
  * `recovery setup` — put the keys of every team THIS MACHINE reports into the
  * account's vault.
@@ -282,7 +278,13 @@ export async function cmdVaultPut(config, args) {
     // backed-up ones are not known until the loop below has run. Hence the
     // parameters: the groups are passed in rather than closed over, so the
     // heading cannot outrun what is under it.
-    const coverage = (written, unchanged) => {
+    // `stranded` joins written/unchanged as a PARAMETER for the reason the two
+    // above are parameters: this function is defined before the loop fills any
+    // of them, and closing over a list that is still empty here prints a
+    // heading with nothing under it. The first version of this got that wrong
+    // in the other direction and listed the disconnected teams under
+    // "Covered".
+    const coverage = (written, unchanged, stranded) => {
         const group = (title, members) => members.length === 0 ? [] : [`\n  ${title}\n`, ...members.map((m) => `    ${m}\n`)];
         // The first two hold for either form — a run that names one team still has
         // to say what it did with it. The rest are about the ENUMERATION, so they
@@ -291,6 +293,12 @@ export async function cmdVaultPut(config, args) {
         const lines = [
             ...group('Backed up in this revision:', written),
             ...group('Already current, nothing to write:', unchanged),
+            // FIRST among the things that did not happen, and with the reason
+            // attached. This is the only group whose members are a contradiction in
+            // the store rather than a choice the operator made, so it is the one
+            // that needs acting on — and the reason is what says which team's state
+            // to look at, rather than leaving "something failed" for them to locate.
+            ...group('Recorded as connected here, but this machine could not open them:', stranded.map((f) => `${f.team} — ${f.reason}`)),
             ...(!enumerated
                 ? []
                 : group('Disconnected on this machine, left as they are:', disconnected.map((t) => t.team))),
@@ -321,34 +329,96 @@ export async function cmdVaultPut(config, args) {
         let next = container;
         const written = [];
         const unchanged = [];
+        // Recorded as connected by this machine, and not openable by it. Kept
+        // apart from `unseen` and `disconnected` because it is a third fact: the
+        // machine reported this team AND could not produce its keys, which is the
+        // store disagreeing with itself rather than a team the operator retired.
+        const couldNotOpen = [];
         for (const [i, target] of targets.entries()) {
             const bundleFile = join(scratch, `handoff-${i}.bundle`);
-            await keyHandoff(config.scriptsDir, target.team, bundleFile);
-            const bundle = readFileSync(bundleFile);
-            const keyIds = bundleKeyIds(bundle);
-            const already = next.teams.find((e) => e.server_instance_id === target.serverInstanceId && e.team_id === target.teamId);
-            if (already && sameEpochs(already.key_ids, keyIds)) {
-                unchanged.push(target.team);
+            // ONE TEAM THIS MACHINE CANNOT OPEN DOES NOT DECIDE THE ACCOUNT (#276).
+            //
+            // The enumeration and this loop read DIFFERENT sources of truth, and
+            // that is the whole defect. `remote.sh status --json` reads only
+            // `teams/<team>/config`: a binding with a `connected_at` and no
+            // `disconnected_at` is reported active, and that read never opens
+            // `db/remote-sync/<team>.json`. The key handoff does. So a team whose
+            // binding record outlived its sync state arrives here looking ordinary
+            // and throws — measured on the 2026-08-11 walk, where a leftover named
+            // `oss-rc2` stopped the backup of four intact teams.
+            //
+            // The failure was TOTAL, and its blast radius was set by the oldest
+            // leftover on the machine rather than by anything the operator was
+            // doing. Skipping and naming is the answer, not refusing to start: this
+            // command already reports what it did not cover — `unseen`,
+            // `disconnected` — instead of refusing, for the same reason. A backup of
+            // four teams that says which fifth is missing leaves someone strictly
+            // better off than a backup of none; a backup of four that said nothing
+            // would not, which is why this is a report and not a silence.
+            //
+            // Any failure, not a matched message. Parsing `ENOENT` would name one
+            // shape of one version of one script, and the honest claim here is
+            // narrower: this machine could not produce this team's keys. The reason
+            // is carried through verbatim for whoever reads it.
+            let bundle;
+            try {
+                await keyHandoff(config.scriptsDir, target.team, bundleFile);
+                bundle = readFileSync(bundleFile);
+            }
+            catch (err) {
+                couldNotOpen.push({
+                    team: target.team,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
                 continue;
             }
-            next = upsertTeam(next, {
+            const keyIds = bundleKeyIds(bundle);
+            // The decision and the write are one call, in the container module, so
+            // `connect` cannot make the same decision differently (#181).
+            const result = upsertTeamIfMoved(next, {
                 server_instance_id: target.serverInstanceId,
                 team_id: target.teamId,
                 key_ids: keyIds,
                 bundle: bundle.toString('base64'),
             });
-            written.push(target.team);
+            next = result.container;
+            (result.written ? written : unchanged).push(target.team);
         }
         // Nothing moved, and the vault already exists: there is no version to
         // write. Saying "stored revision N+1" here would be true of the server and
         // false about the account — the point of a revision is that something is
         // different in it.
+        // NOTHING OPENED IS NOT A PARTIAL BACKUP. Skipping a team that cannot be
+        // opened is right while others can; when the whole set fails there is no
+        // backup to report, and writing here would store a container holding no
+        // teams — a recovery key that opens an empty vault, which reads as success
+        // and is worse than the abort this change replaced.
+        //
+        // Found by the test for this change, not by reading it back: the skip made
+        // the loop finish, and every path after the loop assumed finishing meant
+        // something had been filed.
+        if (written.length === 0 && unchanged.length === 0 && couldNotOpen.length > 0) {
+            process.stdout.write(coverage(written, unchanged, couldNotOpen));
+            throw new Error('no team on this machine could be opened, so nothing was backed up.\n' +
+                'Each team above is recorded here as connected while the state its keys ' +
+                'come from is missing.');
+        }
         if (written.length === 0 && version && vdk) {
             // The headline carries no bare count: what "up to date" covers is the
             // list below it, and a number on its own is the thing this was reported
             // for.
-            process.stdout.write(`already up to date — nothing has new keys. Revision stays at ${version.revision}.\n`);
-            process.stdout.write(coverage(written, unchanged));
+            //
+            // AND IT NARROWS TO WHAT WAS OPENED. "nothing has new keys" is a claim
+            // over every team on the machine, but a team that could not be opened
+            // had its bundle and key epoch read zero times — whether it has new keys
+            // is not a thing this run knows. Unqualified, the line contradicts the
+            // coverage printed two statements later, which names that same team as
+            // one this run could not open (review P1-contract).
+            process.stdout.write(couldNotOpen.length > 0
+                ? `the teams this machine could open have no new keys; the ones below ` +
+                    `it could not open were not checked. Revision stays at ${version.revision}.\n`
+                : `already up to date — nothing has new keys. Revision stays at ${version.revision}.\n`);
+            process.stdout.write(coverage(written, unchanged, couldNotOpen));
             // A run that had to type the key still earns a slot: the key is in hand,
             // and the next run should not ask again just because this one had nothing
             // to store.
@@ -389,7 +459,7 @@ export async function cmdVaultPut(config, args) {
         // (agmsg#650). Teams already in the vault are covered by the refusal
         // higher up; a team that has never been in it cannot be seen from here at
         // all, so the sentence stops at the machine rather than the account.
-        process.stdout.write(coverage(written, unchanged));
+        process.stdout.write(coverage(written, unchanged, couldNotOpen));
         // After the write, and only when this run had to reach the key. A run the
         // slot already answered has a working slot at this address; saving again
         // would mint a fresh KEK, replace it, and touch the keychain on every
@@ -406,9 +476,28 @@ export async function cmdVaultPut(config, args) {
             // filing a key that opens nothing and trusting it for years. A re-run
             // mints a new one, which is correct — and only correct if they know to
             // discard this one.
+            // A REMEDY THAT IS PRINTED HAS TO END SOMEWHERE (#276).
+            //
+            // This used to say "running this command again will show you a new key",
+            // full stop. It does show a new key — and then fails in the same place,
+            // because re-running creates nothing that was missing. On the
+            // 2026-08-11 walk that sentence was followed each time, and each attempt
+            // burned a key and arrived back here, with the failure still advising
+            // the retry.
+            //
+            // Discarding the key is still right and still first: it opens nothing,
+            // and someone who files it will trust it for years. What changed is the
+            // second half — a bare retry is only the answer when the cause was
+            // transient, and this exit does not know that it was. So it names the
+            // condition to check instead, and offers the narrow form, which is the
+            // one thing that lets an account with a broken leftover back up the team
+            // actually in use.
             process.stdout.write('\nThe backup did NOT complete, so the recovery key above was never used\n' +
-                'and opens nothing. Discard it. Running this command again will show you\n' +
-                'a new key.\n\n');
+                'and opens nothing. Discard it.\n\n' +
+                'Re-running is only worth it if the cause above was temporary. If a team\n' +
+                'could not be opened, re-running will stop at the same place and cost you\n' +
+                'another key — back up the one you are using instead:\n\n' +
+                '    agmsg-cloud recovery setup <team>\n\n');
         }
         throw err;
     }
@@ -419,7 +508,11 @@ export async function cmdVaultPut(config, args) {
 // The key epochs the bundle declares, for the entry's binding. This is the only
 // part of the bundle the cloud side reads: everything else is carried opaquely
 // and handed back to the OSS unlock path, so the bundle's format stays theirs.
-function bundleKeyIds(bundle) {
+// Exported alongside slotAddress, and for the same reason: vault-filing.ts
+// writes the same entry shape from connect, and a second reading of the
+// bundle that disagreed would record a binding to key epochs the bundle does
+// not declare.
+export function bundleKeyIds(bundle) {
     try {
         const parsed = JSON.parse(bundle.toString('utf8'));
         const ids = (parsed.identities ?? [])

package/dist/src/commands/whoami.js

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

package/dist/src/config.js

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