agmsg-cloud 0.1.2 → 0.1.4

package/dist/src/authenticated-digest.js

@@ -2,6 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { closeSync, constants, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, statSync, chmodSync, rmSync, writeSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { syncDirectoryEntryIfSupported } from './durable-dir.js';
 /**
  * Identify the (credential, device identity) pair without storing either.
  *
@@ -77,6 +78,35 @@ export function writeAll(fd, bytes, what, write = writeSync) {
  * temp file, fsync, rename, fsync the directory — because a half-written
  * record is one `fetch` would either reject a good bundle over or, worse, read
  * a truncated digest from.
+ *
+ * Also clears any OTHER record already held for this same (origin, scope)
+ * (#523). A machine that stalls after this ceremony — the bundle never
+ * fetched — and then connects again performs a SECOND ceremony for the same
+ * credential and device, and without this the old approval sat beside the
+ * new one forever: `fetch` finds two records for one scope and, correctly,
+ * refuses to guess which bundle either belongs to. There is exactly one live
+ * approval per (credential, device) at a time, so the new one replacing the
+ * old is not a loss — the old one was already superseded the moment this
+ * ceremony ran, since it authenticates the account's current snapshot, not a
+ * fixed past one.
+ *
+ * Two ceremonies for the SAME credential and device, running at once, only
+ * clear records OLDER than the one each just wrote (raised in review) —
+ * never the newest, and never each other. Without that qualifier, two
+ * concurrent calls could each write their own record and then each delete
+ * the OTHER's, leaving zero records for a scope that just ran two
+ * successful ceremonies — worse than the pile-up this exists to fix. This
+ * guarantees the scope is never left with zero records, however two
+ * genuinely concurrent calls interleave; it does not by itself guarantee
+ * they converge to exactly one (a pair racing closely enough can both
+ * survive, since each only knows what predates it, not what is still being
+ * written elsewhere). Running two ceremonies for one scope at once is out
+ * of scope to serialize against, deliberately — nobody starts a second
+ * `request` on top of one already in flight. What this fix exists to
+ * guarantee, and does, is the case that actually happens: from a stuck
+ * two-record state, one ordinary retry always recovers to exactly one,
+ * because that retry's own record is newer than both existing ones and
+ * clears them both in the same pass.
  */
 export function recordAuthenticatedDigest(input, env = process.env) {
     if (!HEX64.test(input.handoffDigest)) {
@@ -93,10 +123,11 @@ export function recordAuthenticatedDigest(input, env = process.env) {
     // from the first one — the same reason credentials.ts does it (raised in review).
     enforceMode(dir, 0o700);
     const path = pathFor(dir, input.serverOrigin, input.requestId);
+    const scope = fingerprintScope(input.secret, input.devicePubkey);
     const record = {
         requestId: input.requestId,
         handoffDigest: input.handoffDigest,
-        scopeFingerprint: fingerprintScope(input.secret, input.devicePubkey),
+        scopeFingerprint: scope,
         recordedAt: new Date().toISOString(),
     };
     const tmp = `${path}.${randomBytes(8).toString('hex')}.tmp`;
@@ -138,12 +169,119 @@ export function recordAuthenticatedDigest(input, env = process.env) {
         throw err;
     }
     enforceMode(path, 0o600);
-    const dirFd = openSync(dirname(path), constants.O_RDONLY);
+    // The same POSIX-only directory flush as `credentials.ts`, and the same
+    // reason it is now probed rather than assumed (#512). Fixing only the other
+    // site would have moved the EPERM here instead of removing it.
+    syncDirectoryEntryIfSupported(dirname(path));
+    // AFTER the new record is durably in place, never before: deleting the old
+    // one first would leave a window with zero records for this scope if the
+    // write above failed partway. Best-effort from here — see
+    // removeOlderRecordsForScope — because the new record above is already
+    // durable, and nothing below may throw back to a caller who would only
+    // retry and pile up yet another new record (raised in review).
+    removeOlderRecordsForScope(dir, input.serverOrigin, scope, input.requestId, record.recordedAt);
+}
+/**
+ * Best-effort cleanup of every OTHER, OLDER record this (origin, scope)
+ * still holds — older BY `recordedAt`, strictly, never equal or newer
+ * (raised in review). That qualifier is what keeps this safe under two
+ * concurrent ceremonies for the same scope: each of the two only deletes
+ * what it can already tell predates it, so neither ever deletes the other
+ * when both are genuinely new, and whichever of the two IS the newest is
+ * never deleted by the other. What this does NOT guarantee: running two
+ * ceremonies for one scope AT THE SAME TIME can still leave both of their
+ * records behind — deliberately out of scope, since nobody runs a second
+ * `request` on top of one already in flight, and this never claims a
+ * concurrent pair converges to one on its own. What it does guarantee is
+ * the case that matters: from that stuck two-record state, ONE ordinary
+ * retry always recovers it, because the retry's own record is newer than
+ * both and this cleanup removes them both in that single pass. Never zero,
+ * either way, is unconditional.
+ *
+ * Best-effort, not authoritative, in two more ways. A neighbour this cannot
+ * parse, or whose `recordedAt` this cannot confidently compare, is left
+ * alone rather than guessed at, because a wrongly-deleted approval is a
+ * fetch nobody can complete, while a wrongly-kept one is only a state
+ * `fetch`'s own multiple-record refusal already handles. And a deletion that
+ * FAILS is caught rather than thrown, for the same reason: this runs after
+ * the new record is already durable, so throwing here would report failure
+ * for a call that mostly succeeded, and a caller who retries on that error
+ * would only record ANOTHER new approval on top (raised in review). Either
+ * way, `fetch`'s refusal stays the backstop for whatever this pass cannot
+ * confidently remove.
+ */
+function removeOlderRecordsForScope(dir, origin, scope, keepRequestId, keepRecordedAt) {
+    const prefix = `${Buffer.from(origin, 'utf8').toString('base64url')}.`;
+    let names;
     try {
-        fsyncSync(dirFd);
+        names = readdirSync(dir);
     }
-    finally {
-        closeSync(dirFd);
+    catch {
+        // Same reasoning as a failed deletion below: the new record is already
+        // durable, so a directory this cannot even list must not fail the call.
+        return;
+    }
+    let removedAny = false;
+    for (const name of names) {
+        if (!name.startsWith(prefix) || !name.endsWith('.json'))
+            continue;
+        const candidate = join(dir, name);
+        let parsed;
+        try {
+            const fd = openSync(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+            try {
+                parsed = JSON.parse(readFileSync(fd, 'utf8'));
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        const r = parsed;
+        if (typeof r?.['requestId'] !== 'string' || r['requestId'] === keepRequestId)
+            continue;
+        if (r['scopeFingerprint'] !== scope)
+            continue;
+        // Strictly older, by ISO-8601 string comparison — valid because
+        // `recordedAt` is always written by `toISOString()` here, a fixed-width
+        // format lexical order agrees with chronological order on. Equal or
+        // unreadable is NOT older: a missing/malformed timestamp cannot be
+        // confidently placed before this one, and a tie (two ceremonies stamped
+        // in the same millisecond) must not delete either — that is what keeps
+        // a concurrent pair from being able to empty the scope between them.
+        if (typeof r['recordedAt'] !== 'string' || !(r['recordedAt'] < keepRecordedAt))
+            continue;
+        try {
+            rmSync(candidate, { force: true });
+            removedAny = true;
+        }
+        catch {
+            continue;
+        }
+    }
+    // Once, after every deletion in this pass, not per file: one flush covers
+    // everything this call removed. Without it, a crash right after could roll
+    // a removal back on disk while this pass has already moved on — putting the
+    // old record back and reintroducing the exact stuck state this cleanup
+    // exists to prevent (raised in review).
+    //
+    // Caught, not thrown (raised in review): this whole function runs after
+    // the caller's own new record is already durable, so a failure HERE must
+    // not be reported back as the call having failed — that would tell a
+    // caller whose write actually succeeded to retry, and a retry only
+    // records yet another new approval on top.
+    if (removedAny) {
+        try {
+            syncDirectoryEntryIfSupported(dir);
+        }
+        catch {
+            // Best-effort, like the deletions themselves: the files are gone from
+            // the directory listing either way, and `fetch`'s own multiple-record
+            // refusal is what protects a machine if this particular flush is what
+            // a crash rolls back.
+        }
     }
 }
 /**

package/dist/src/bash-path.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+/**
+ * Git for Windows' usual homes, most specific first.
+ *
+ * `System32\bash.exe` is deliberately NOT on this list and is never chosen
+ * explicitly: it reaches PATH on its own, and if it is the only thing there
+ * then that is what gets reported rather than silently substituted.
+ */
+function gitBashCandidates(env) {
+    const local = env['LOCALAPPDATA'];
+    const programFiles = env['ProgramFiles'] ?? 'C:\\Program Files';
+    const programFilesX86 = env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+    return [
+        ...(local ? [`${local}\\Programs\\Git\\bin\\bash.exe`] : []),
+        `${programFiles}\\Git\\bin\\bash.exe`,
+        `${programFilesX86}\\Git\\bin\\bash.exe`,
+    ];
+}
+/**
+ * The interpreter to run the OSS shell scripts with.
+ *
+ * `AGMSG_BASH` wins outright and is not checked for existence — an operator
+ * naming a path is making a statement, and silently ignoring it when the path
+ * is wrong would put us back to guessing. A bad value fails at the spawn, with
+ * that value named.
+ *
+ * `deps` exists so a test can drive the Windows branches from any platform.
+ */
+export function resolveBash(env = process.env, deps = {}) {
+    const override = env['AGMSG_BASH'];
+    if (override)
+        return { command: override, source: 'AGMSG_BASH' };
+    const platform = deps.platform ?? process.platform;
+    if (platform === 'win32') {
+        const exists = deps.exists ?? existsSync;
+        for (const candidate of gitBashCandidates(env)) {
+            if (exists(candidate))
+                return { command: candidate, source: 'git-bash' };
+        }
+    }
+    return { command: 'bash', source: 'PATH' };
+}
+/** One clause naming the interpreter, for a message a person has to act on. */
+export function describeBash(r) {
+    if (r.source === 'AGMSG_BASH')
+        return `${r.command} (from AGMSG_BASH)`;
+    if (r.source === 'git-bash')
+        return `${r.command} (Git for Windows)`;
+    return `${r.command} (first on PATH)`;
+}

package/dist/src/commands/connect.js

@@ -1,4 +1,5 @@
 import { spawnOssInherit } from '../oss-env.js';
+import { resolveBash } from '../bash-path.js';
 import { existsSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { CourierClient, CourierError } from '../api.js';
@@ -35,7 +36,7 @@ export async function cmdConnect(config, opts) {
     }
     process.stdout.write(`\nConnecting "${opts.team}" as machine "${credential.machineName}".\n`);
     const run = opts.runner ?? runInherit;
-    const code = await run('bash', [
+    const code = await run(resolveBash().command, [
         join(config.scriptsDir, 'remote.sh'),
         'connect',
         '--endpoint',

package/dist/src/commands/fetch.js

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { CourierClient } from '../api.js';
 import { clearAuthenticatedDigest, readAuthenticatedDigests } from '../authenticated-digest.js';
 import { originOf } from '../credentials.js';
+import { shellArg } from '../shell-arg.js';
 import { decryptWithIdentity, localTeamLookup, publicKeyOf, unlockBundle, verifyHandoffDigest, } from '../oss.js';
 import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
@@ -107,7 +108,11 @@ env = process.env) {
             // not a weaker check — it is no check, in the shape of one.
             const ids = authenticated.map((a) => `  ${a.requestId}  (${a.recordedAt})`).join('\n');
             throw new Error(`${authenticated.length} approved enrollments are recorded for this service:\n\n${ids}\n\n` +
-                'Which one this bundle belongs to cannot be decided from here.');
+                'Which one this bundle belongs to cannot be decided from here.\n\n' +
+                `Run \`agmsg-cloud sync ${shellArg(args.team)}\` again and have it approved: a\n` +
+                'fresh approval replaces every other one recorded here for this machine, leaving\n' +
+                'exactly one. (Run `agmsg-cloud request <label>` instead if this machine got here\n' +
+                'through `request` on its own rather than through `sync`.)');
         }
         const consumed = authenticated[0];
         const expected = consumed.handoffDigest;

package/dist/src/commands/pull.js

@@ -1,6 +1,7 @@
 import { spawnOssInherit } from '../oss-env.js';
 import { shellArg } from '../shell-arg.js';
 import { join } from 'node:path';
+import { resolveBash } from '../bash-path.js';
 import { CourierClient, isUuid } from '../api.js';
 import { originOf, readCredential } from '../credentials.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
@@ -30,7 +31,7 @@ export async function cmdPull(config, opts) {
     const teamId = opts.teamId ?? (await resolveTeamId(config, opts));
     process.stdout.write(`\nPulling "${opts.team}" onto machine "${credential.machineName}".\n`);
     const run = opts.runner ?? runInherit;
-    const code = await run('bash', [
+    const code = await run(resolveBash().command, [
         join(config.scriptsDir, 'remote.sh'),
         'pull',
         '--endpoint',
@@ -52,8 +53,16 @@ export async function cmdPull(config, opts) {
     // What it adds is the route, which the OSS script no longer names because
     // its route is not ours. Phrased as a condition rather than a claim, so it
     // is true after either line above.
-    process.stdout.write(`\n"${opts.team}" is on this machine.\n`);
+    //
+    // BOTH lines withheld under `nextStepsFromCaller`, not just the route
+    // (#523). `sync` runs `fetch` immediately after this, and "is on this
+    // machine" reads as this step's own success — which it is — right before a
+    // failing `fetch` throws with nothing to say the two are different steps.
+    // The caller owns saying what happened once every one of its steps has
+    // run; this side saying its own half early is what let the two read as one
+    // outcome.
     if (opts.nextStepsFromCaller !== true) {
+        process.stdout.write(`\n"${opts.team}" is on this machine.\n`);
         process.stdout.write(`If it is still locked, \`agmsg-cloud sync ${shellArg(opts.team)}\` completes the key handoff:\n` +
             'it asks a machine that already has the team, and the two of you compare eight digits.\n');
     }

package/dist/src/commands/sync.js

@@ -216,7 +216,19 @@ export async function cmdSync(config, opts) {
     // server says the ceremony was approved — `request` waits for that, and
     // throws otherwise. The bundle is checked against the snapshot those digits
     // authenticated, by machine.
-    await fetch(config, { team: opts.team });
+    //
+    // `pull` no longer says anything on its own when it is a step of this
+    // command (#523), so if this throws, nothing above has claimed success yet
+    // — the operator has only been told the ceremony finished. Said here,
+    // before the error propagates, so a failure at this LAST step still reads
+    // as a failure and not as a silent stop after what looked like the finish.
+    try {
+        await fetch(config, { team: opts.team });
+    }
+    catch (err) {
+        out(`\n"${opts.team}" is on this machine, but the key has not arrived — it cannot be used yet.\n`);
+        throw err;
+    }
     // The last thing said, because "what now" is the question the screen leaves
     // otherwise: someone who has just run five steps and watched a code
     // comparison has every reason to expect a sixth.

package/dist/src/credentials.js

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, statSync, chmodSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { syncDirectoryEntryIfSupported } from './durable-dir.js';
 /**
  * A server-minted org address, in either of the two forms the server mints.
  *
@@ -489,14 +490,20 @@ function commit(path, dir, next) {
     enforceFileMode(path);
     // Rename is atomic but not durable until the DIRECTORY entry is flushed. The
     // whole point of writing before activating is that a crash here still leaves
-    // the credential on disk, so this fsync is load-bearing, not hygiene.
-    const dirFd = openSync(dir, constants.O_RDONLY);
-    try {
-        fsyncSync(dirFd);
-    }
-    finally {
-        closeSync(dirFd);
-    }
+    // the credential on disk, so this fsync is load-bearing, not hygiene —
+    // ON POSIX. That qualifier is new and it is the whole of #512: Windows has
+    // no directory fsync, the call failed with EPERM, and `login` died after the
+    // server exchange had already succeeded. The comment as it stood said
+    // "load-bearing" without a platform and would have told the next reader that
+    // Windows was getting a guarantee it never had.
+    //
+    // Where the operation does not exist, the credential is still written and
+    // renamed; what is missing is the flush. THIS CALL DOES NOT TELL US WHICH
+    // HAPPENED, and the comment here used to say it did — the helper returned an
+    // outcome and this line dropped it, so "the caller can tell the difference"
+    // was true of the test suite and false of the product. It is best-effort now
+    // and says so. Anything that is not a capability answer still throws.
+    syncDirectoryEntryIfSupported(dir);
 }
 // Used only by the tests that need a file on disk without going through a
 // login; kept here so the 0600/0700 rules live in exactly one place.

package/dist/src/durable-dir.js

@@ -0,0 +1,129 @@
+import { closeSync, constants, fsyncSync, openSync } from 'node:fs';
+// FLUSHING A DIRECTORY ENTRY, WHERE THAT IS A THING (#512).
+//
+// After `rename`, POSIX gives atomicity but not durability: the entry is not on
+// disk until the containing DIRECTORY is fsynced. Both call sites write a file,
+// rename it into place, and then flush the directory, and the comment at one of
+// them called that "load-bearing, not hygiene". On POSIX it is.
+//
+// Windows has no such operation, and a user hit it: `agmsg-cloud login` printed
+// its device code, completed the exchange, and then died with
+//
+//     EPERM: operation not permitted, fsync
+//
+// on the last line of storing the credential — after the part that talks to the
+// server, before the part that makes it usable.
+//
+// READ THE SYSCALL IN THAT MESSAGE. It says `fsync`, so on that machine the
+// open SUCCEEDED and the flush was refused. An earlier version of this file
+// asserted the opposite in a comment — "Windows refuses at the OPEN, not at the
+// fsync" — two paragraphs below the error text that contradicts it. Nobody
+// measured it; it was inferred from how directories open elsewhere and then
+// written down as fact. The open is guarded too, but as a precaution, and it is
+// labelled as one below.
+//
+// THE FIX IS NOT AN EQUIVALENT. There is no Windows call that buys the same
+// guarantee here; `MoveFileEx` reasons about durability differently. So this
+// does not "do the same thing another way" — where the guarantee is
+// unavailable, the entry is written and renamed and the flush does not happen,
+// and that is a downgrade we accept rather than a success we claim.
+/**
+ * Refusals that mean "this filesystem does not offer the operation", whatever
+ * the platform.
+ *
+ * Deliberately small. A directory fsync is refused with `EINVAL` or `ENOTSUP`
+ * by filesystems that do not implement it — some network and FUSE mounts — and
+ * those answers are not ambiguous. Adding an errno here needs the same
+ * argument: that it CANNOT also be a real failure of this particular write.
+ */
+const NOT_OFFERED_ANYWHERE = new Set(['EINVAL', 'ENOTSUP']);
+/**
+ * Refusals that mean "unsupported" ONLY on Windows, because on POSIX they are
+ * how a real failure of a real operation arrives.
+ *
+ * `EPERM` is the one the reported crash produced. On POSIX the same errno is a
+ * genuine refusal, so reading it as a capability answer everywhere would turn
+ * real failures into silent successes. It is gated on the platform for exactly
+ * that reason — see the note on `deps.platform`.
+ */
+const NOT_OFFERED_ON_WINDOWS = new Set(['EPERM', 'EISDIR']);
+/**
+ * `EACCES` is in NEITHER set, and this is the line most likely to be
+ * "simplified" later.
+ *
+ * It is a permission answer, not a capability answer: a directory whose search
+ * permission was dropped, an ACL, a sandbox policy. Swallowing it would report
+ * a successful sign-in over a filesystem that is refusing us — which is the
+ * failure this whole file exists to remove, pointing the other way. Same for
+ * `ENOENT`: the directory the caller just renamed into being gone is not a
+ * portability question.
+ */
+function isUnsupported(err, phase, platform) {
+    const code = err.code ?? '';
+    if (phase === 'fsync' && NOT_OFFERED_ANYWHERE.has(code))
+        return true;
+    return platform === 'win32' && NOT_OFFERED_ON_WINDOWS.has(code);
+}
+/**
+ * Flush a directory entry where the platform offers it, and do nothing where it
+ * does not.
+ *
+ * Returns `void`, and the contract is the honest version of that: **this is
+ * best-effort durability.** An earlier draft returned `'flushed' | 'unsupported'`
+ * so that a caller "could tell the difference" — and neither caller looked at
+ * it. A union nobody reads is not a report; it only makes the prose around it
+ * sound like one. If we ever need to tell a user that their filesystem cannot
+ * promise this, that is a change at the call sites, and the return type comes
+ * back with it.
+ *
+ * Everything that is not a capability answer still throws.
+ *
+ * `deps.platform` exists because two errnos are ambiguous, not because the
+ * platform decides whether the call works. The call itself still answers that —
+ * probed, never assumed — and a filesystem refusing with `EINVAL` is honoured on
+ * any platform. What the platform gates is how to READ `EPERM`, which means one
+ * thing on Windows and another on Linux.
+ *
+ * The rest of `deps` is there so a test can drive these branches from any
+ * platform: there is no way to make a real POSIX kernel refuse this on demand.
+ */
+export function syncDirectoryEntryIfSupported(dir, deps = {}) {
+    const open = deps.open ?? openSync;
+    const fsync = deps.fsync ?? fsyncSync;
+    const close = deps.close ?? closeSync;
+    const platform = deps.platform ?? process.platform;
+    let dirFd;
+    try {
+        dirFd = open(dir, constants.O_RDONLY);
+    }
+    catch (err) {
+        // PRECAUTION, NOT THE REPORTED CRASH. The machine that reported this got
+        // past the open; guarding here covers a Windows build or a mount that
+        // refuses earlier, and costs nothing when it does not.
+        if (isUnsupported(err, 'open', platform))
+            return;
+        throw err;
+    }
+    try {
+        fsync(dirFd);
+    }
+    catch (err) {
+        // Close before deciding, and do not let the close's own failure become the
+        // error the caller sees: it would replace a diagnosis with a symptom.
+        try {
+            close(dirFd);
+        }
+        catch {
+            // Intentionally dropped. The fsync error below is the one that explains
+            // what happened; a close error on a descriptor we are abandoning is not.
+        }
+        if (isUnsupported(err, 'fsync', platform))
+            return;
+        throw err;
+    }
+    // Success path only, so this close is the sole thing that can still fail —
+    // and a close reporting a deferred write error is a real failure of this
+    // write, not a portability answer. It throws, matching how both call sites
+    // already treat `closeSync` on the file itself.
+    close(dirFd);
+}

package/dist/src/oss.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { closeSync, constants, openSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnOssPiped } from './oss-env.js';
+import { describeBash, resolveBash } from './bash-path.js';
 // Thin wrappers over the OSS tooling. The proprietary courier never touches key
 // material: sealing/opening the bundle and the handoff/unlock steps all run
 // through `age` and the OSS `key.sh` / `remote.sh` on the operator's machine.
@@ -66,13 +67,32 @@ export function runAllowingFailure(cmd, args) {
  * not get presented to the operator as a mistyped name.
  */
 export async function localTeamLookup(scriptsDir, team) {
-    const r = await runAllowingFailure('bash', [
+    const bash = resolveBash();
+    const r = await runAllowingFailure(bash.command, [
         join(scriptsDir, 'remote.sh'),
         'status',
         team,
         '--json',
     ]);
-    return r.code === 0 ? { known: true, said: '' } : { known: false, said: r.stderr };
+    if (r.code === 0)
+        return { known: true, said: '' };
+    // THE DEFENCE IS EMPTY EXACTLY WHEN IT IS NEEDED (#507).
+    //
+    // `fetch.ts` prints `said` so the operator can tell "no such team" from "the
+    // store could not be read". That works while the script runs and complains.
+    // A process that never started writes nothing to stderr, so `said` is empty
+    // in the one case the two readings are hardest to tell apart — and the empty
+    // string is dropped from the message, leaving only the ambiguity with no
+    // evidence attached.
+    //
+    // So when the store said nothing, name the interpreter instead. It is not a
+    // diagnosis: it is the one fact this layer holds that the operator does not,
+    // and on Windows it is usually the whole answer (`System32\bash.exe` is the
+    // WSL launcher, not a shell that can run these scripts — #505).
+    return {
+        known: false,
+        said: r.stderr === '' ? `nothing. Interpreter tried: ${describeBash(bash)}` : r.stderr,
+    };
 }
 // Generate a device age identity at `identityPath`; returns its public recipient.
 export async function generateDeviceIdentity(identityPath) {
@@ -95,7 +115,7 @@ export function decryptWithIdentity(identityPath, ciphertext) {
 // OSS `key.sh handoff <team> --out <file>` — export the one secret handoff bundle
 // (confirmed snapshot chain + every epoch identity) for `team`.
 export async function keyHandoff(scriptsDir, team, outFile) {
-    await run('bash', [join(scriptsDir, 'key.sh'), 'handoff', team, '--out', outFile]);
+    await run(resolveBash().command, [join(scriptsDir, 'key.sh'), 'handoff', team, '--out', outFile]);
 }
 // OSS `remote-sync.sh verify-age-handoff` — the digest the joiner's `unlock`
 // will compare the human-carried value against.
@@ -112,7 +132,7 @@ export async function keyHandoff(scriptsDir, team, outFile) {
 // and is already on disk beside it — but the directory holds private key
 // material and must be treated exactly like the bundle.
 export async function verifyHandoffDigest(scriptsDir, team, bundleFile, outDir) {
-    const out = await run('bash', [
+    const out = await run(resolveBash().command, [
         join(scriptsDir, 'remote-sync.sh'),
         'verify-age-handoff',
         '--team',
@@ -153,7 +173,7 @@ export async function verifyHandoffDigest(scriptsDir, team, bundleFile, outDir)
 // material came from. `remoteTeamId` stays for callers that only address the
 // team, so neither has to know about the other's fields.
 export async function remoteBinding(scriptsDir, team) {
-    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
+    const out = await run(resolveBash().command, [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
     const text = out.toString().trim();
     if (!text)
         throw new Error(`team '${team}' has never been connected to a remote`);
@@ -173,7 +193,7 @@ export async function remoteBinding(scriptsDir, team) {
     return { teamId: status.remote_team_id, serverInstanceId: status.server_instance_id };
 }
 export async function connectedTeams(scriptsDir) {
-    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', '--json']);
+    const out = await run(resolveBash().command, [join(scriptsDir, 'remote.sh'), 'status', '--json']);
     const teams = [];
     for (const line of out.toString().split('\n')) {
         const text = line.trim();
@@ -245,7 +265,7 @@ export async function teamsBoundTo(scriptsDir, origin) {
     return { matched: matched.sort(), unreadable: unreadable.sort() };
 }
 export async function remoteTeamId(scriptsDir, team) {
-    const out = await run('bash', [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
+    const out = await run(resolveBash().command, [join(scriptsDir, 'remote.sh'), 'status', team, '--json']);
     const text = out.toString().trim();
     if (!text)
         throw new Error(`team '${team}' has never been connected to a remote`);
@@ -275,7 +295,7 @@ export async function remoteTeamId(scriptsDir, team) {
 // courier path must keep using unlockBundle with an out-of-band digest, because
 // age's recipient encryption does not authenticate the sender.
 export async function unlockAuthenticatedBundle(scriptsDir, team, bundle) {
-    await run('bash', [join(scriptsDir, 'remote.sh'), 'unlock', team, '--authenticated-bundle-stdin'], bundle);
+    await run(resolveBash().command, [join(scriptsDir, 'remote.sh'), 'unlock', team, '--authenticated-bundle-stdin'], bundle);
 }
 // OSS `remote.sh unlock <team> --bundle <file> [--confirm-digest <digest>]`.
 //
@@ -296,7 +316,7 @@ export async function unlockBundle(scriptsDir, team, bundleFile, confirmDigest)
     const args = [join(scriptsDir, 'remote.sh'), 'unlock', team, '--bundle', bundleFile];
     if (confirmDigest)
         args.push('--confirm-digest', confirmDigest);
-    return (await run('bash', args)).toString();
+    return (await run(resolveBash().command, args)).toString();
 }
 // The canonical age snapshot, exported locally, and its digest (§3.2, §3.2.1).
 //
@@ -311,7 +331,7 @@ export async function unlockBundle(scriptsDir, team, bundleFile, confirmDigest)
 // without anything failing. Reading the definition rather than the message
 // also means A and B compute the same value from the same rule.
 export async function exportSnapshotDigest(scriptsDir, team, outPath) {
-    await run('bash', [
+    await run(resolveBash().command, [
         join(scriptsDir, 'remote-sync.sh'),
         'export-age-snapshot',
         '--team',

package/dist/src/preflight.js

@@ -2,6 +2,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { defaultScriptsDir, hasCredential, scriptsDirChoice } from './config.js';
 import { join } from 'node:path';
+import { describeBash, resolveBash } from './bash-path.js';
 import { platform } from 'node:process';
 import { selfInstall } from './self-install.js';
 // What `connect` needs before it starts, checked all at once.
@@ -33,7 +34,7 @@ import { selfInstall } from './self-install.js';
 // cannot establish that a silently short team list is impossible.
 export function installedVersion(scriptsDir) {
     try {
-        const out = execFileSync('bash', [join(scriptsDir, 'version.sh')], {
+        const out = execFileSync(resolveBash().command, [join(scriptsDir, 'version.sh')], {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
         }).trim();
@@ -70,31 +71,28 @@ export function supportsFailClosedTeamStatus(version) {
         return patch > 0;
     return rc === null || rc >= 4;
 }
-// Does the installed remote.sh offer `connect`? Asked of the script itself: run
-// with no arguments it prints its usage, which names the subcommands it has.
-//
-// This is capability detection, not version detection, and the difference is
-// the point — see the note above `installedVersion`.
-//
-// What is deliberately NOT probed: whether this install carries the fix for the
-// store-migration data-loss path. There is no way to ask a script "do you have
-// this guard" without reading its innards and guessing, and a check that cannot
-// really answer is worse than none — it reads as a guarantee. The release plan
-// covers it instead: the fix ships before remote sync is public.
-function remoteSupportsConnect(scriptsDir) {
+export function remoteSupportsConnect(scriptsDir, deps = {}) {
+    const bash = deps.bash ?? resolveBash();
+    const run = deps.run ?? execFileSync;
     try {
-        const out = execFileSync('bash', [join(scriptsDir, 'remote.sh')], {
+        const out = run(bash.command, [join(scriptsDir, 'remote.sh')], {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
         });
-        return /\bconnect\b/.test(out);
+        return /\bconnect\b/.test(out) ? 'yes' : 'no';
     }
     catch (err) {
-        // Usage goes to stderr and exits non-zero in some versions; that output is
-        // just as good an answer as a clean exit.
         const e = err;
         const text = `${String(e.stdout ?? '')}${String(e.stderr ?? '')}`;
-        return /\bconnect\b/.test(text);
+        // Usage on stderr with a non-zero exit is a real answer — the script ran.
+        if (/\bconnect\b/.test(text))
+            return 'yes';
+        // It ran and said nothing about connect: that IS evidence about the script.
+        // Distinguished from never having run by whether either stream produced
+        // anything at all. A spawn failure has neither, and ENOENT names itself.
+        if (e.code === 'ENOENT' || text.length === 0)
+            return 'unknown';
+        return 'no';
     }
 }
 /**
@@ -256,7 +254,9 @@ versionRunner) {
     // than inferred from a version; account-wide recovery separately applies the
     // released producer floor described above `installedVersion`.
     const scriptsPresent = missingScripts.length === 0;
-    const canConnect = scriptsPresent && (!requireConnect || remoteSupportsConnect(scriptsDir));
+    const bash = resolveBash();
+    const connectSupport = scriptsPresent && requireConnect ? remoteSupportsConnect(scriptsDir, { bash }) : 'yes';
+    const canConnect = scriptsPresent && connectSupport === 'yes';
     const agmsgVersion = scriptsPresent ? installedVersion(scriptsDir) : null;
     requirements.push({
         name: requireConnect
@@ -265,11 +265,20 @@ versionRunner) {
         ok: canConnect,
         why: !scriptsPresent
             ? `${command} runs ${missingScripts.join(' and ')}, and this machine has no copy there.`
-            : 'the agmsg installed here does not offer `remote.sh connect`, so it predates remote sync.',
-        install: [
-            'Install or update:   npx agmsg install',
-            'Elsewhere?           point AGMSG_SCRIPTS_DIR at that install\'s scripts directory.',
-        ],
+            : connectSupport === 'unknown'
+                ? // NOT a claim about the install (#505). Nothing was learned about it.
+                    `could not run ${describeBash(bash)}, so nothing here was checked — this says nothing about your agmsg install.`
+                : 'the agmsg installed here does not offer `remote.sh connect`, so it predates remote sync.',
+        install: connectSupport === 'unknown'
+            ? [
+                `Interpreter tried:   ${describeBash(bash)}`,
+                'On Windows the first `bash` on PATH is usually WSL, which cannot run these scripts.',
+                'Point at Git Bash:   set AGMSG_BASH to ...\\Git\\bin\\bash.exe',
+            ]
+            : [
+                'Install or update:   npx agmsg install',
+                'Elsewhere?           point AGMSG_SCRIPTS_DIR at that install\'s scripts directory.',
+            ],
     });
     if (requireFailClosedTeamStatus) {
         requirements.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agmsg-cloud",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",