agmsg-cloud 0.1.1 → 0.1.3

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.
  *
@@ -138,13 +139,10 @@ export function recordAuthenticatedDigest(input, env = process.env) {
         throw err;
     }
     enforceMode(path, 0o600);
-    const dirFd = openSync(dirname(path), constants.O_RDONLY);
-    try {
-        fsyncSync(dirFd);
-    }
-    finally {
-        closeSync(dirFd);
-    }
+    // 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));
 }
 /**
  * Every settled ceremony recorded for this origin.

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

@@ -90,6 +90,30 @@ export function verificationUrlIsSafe(url, endpoint) {
     // operator who named their own endpoint owns their own topology.
     return true;
 }
+/**
+ * The console to send someone to, or null when we do not know one.
+ *
+ * Null is the answer for a self-hosted endpoint, and it is the whole reason
+ * this is a function rather than a constant anyone can print. The pin above
+ * exists because the official console's origin is a name we ship; a
+ * self-hosted deployment's is "not ours to know", and guessing `app.<their
+ * domain>` sends an operator to a service that may not be theirs — or may be
+ * someone else's.
+ *
+ * So a caller that wants to end a message with "and manage it at …" has to
+ * handle the null. That is deliberate: a message with no URL is worse than one
+ * with a wrong URL only until the wrong URL is followed.
+ */
+export function officialConsoleFor(endpoint) {
+    try {
+        return new URL(endpoint).origin === new URL(DEFAULT_ENDPOINT).origin
+            ? OFFICIAL_CONSOLE_ORIGIN
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function openUrl(url) {
     const opener = openerFor(url);
     return new Promise((resolve) => {

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

@@ -3,6 +3,8 @@ import { DEFAULT_ENDPOINT, armEnterToOpen, verificationUrlIsSafe, } from '../bro
 import { credentialsForOrigin, isOrgAddress, originOf, writeCredential } from '../credentials.js';
 import { settleMachineName, validateMachineName } from '../machine-name.js';
 import { resolveScriptsDir } from '../config.js';
+import { packageInstall } from '../version.js';
+import { pathLookupCommand } from '../preflight.js';
 import { teamsBoundTo } from '../oss.js';
 // `login` — the device-authorization flow, from this machine's side.
 //
@@ -360,7 +362,43 @@ async function pollUntilDecided(grant, ctx) {
             // will look up again. Checked here so nothing durable happens first, and
             // checked again in `keyFor` so a future caller cannot route around this.
             if (!isOrgAddress(issued.org)) {
-                throw new Error('the server answered with an org address this build does not recognise — nothing was stored');
+                // WHAT THIS SENTENCE HAS TO GET RIGHT: whose fault it is, and what to
+                // do next. The previous wording — "the server answered with an org
+                // address this build does not recognise" — put the server first, and
+                // the person who hit it concluded the service was broken and stopped
+                // (#476). It was not broken: their machine was running a build from
+                // before `isOrgAddress` learned the second form.
+                //
+                // `credentials.ts` predicts this window in as many words: the server
+                // cutover "does not land until `npm view agmsg-cloud version` resolves
+                // to a build whose `isOrgAddress` accepts the new form". The window was
+                // designed for. What was never written was the sentence someone reads
+                // from inside it.
+                //
+                // The version AND the directory, from `packageInstall()`, which walks
+                // once and returns both. That pairing is the point here rather than a
+                // detail: the machine that hit this had TWO `agmsg-cloud` on PATH, and
+                // the one that answered `-v` was not the one that ran. A version alone
+                // would have been the same ambiguity in a new place. Reading the
+                // directory back against the shell's own lookup is what settles it.
+                //
+                // The lookup command comes from `preflight.ts`, which already had to
+                // decide it: `where` on Windows, `which` elsewhere. Printing `which`
+                // unconditionally would hand a Windows reader a broken command at the
+                // exact moment they have hit the PATH confusion this sentence exists to
+                // resolve. Raised in review, and taken from the module that RUNS it so
+                // the printed advice and the executed lookup cannot drift apart.
+                //
+                // No version number is named as the one to upgrade TO. Naming it needs
+                // a claim about which release first accepted this form, that claim
+                // decays every release, and a reader on that exact version is told to
+                // install what they already have. "Update, then run this again" is
+                // true whatever the answer is.
+                const { version, directory } = packageInstall();
+                throw new Error(`this build (${version}, from ${directory}) does not recognise the org address ` +
+                    'the server sent — nothing was stored. Update with `npm i -g agmsg-cloud` and run ' +
+                    'this command again. If the version above is not the one you expected, another ' +
+                    `\`agmsg-cloud\` is ahead of it on PATH — compare it with \`${pathLookupCommand()} agmsg-cloud\`.`);
             }
             return finish(issued, endpoint, post, out);
         }

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',

package/dist/src/commands/sync.js

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { CourierClient } from '../api.js';
 import { originOf, readCredential } from '../credentials.js';
+import { officialConsoleFor } from '../browser.js';
 import { publicKeyOf } from '../oss.js';
 import { deviceIdentityPath } from '../paths.js';
 import { NEEDS, ensurePreflight, preflight } from '../preflight.js';
@@ -217,8 +218,22 @@ export async function cmdSync(config, opts) {
     // authenticated, by machine.
     await fetch(config, { team: opts.team });
     // The last thing said, because "what now" is the question the screen leaves
-    // otherwise — and here the answer is that there is no next command. Saying
-    // so is the point: someone who has just run five steps and watched a code
+    // otherwise: someone who has just run five steps and watched a code
     // comparison has every reason to expect a sixth.
-    out(`\n"${opts.team}" is on this machine, unlocked and syncing. Nothing further to run.\n`);
+    //
+    // "Nothing further to run" was true and was read as "nothing further to do",
+    // and the walk stopped there (#479). The two are different sentences. There
+    // is no sixth COMMAND, and there is somewhere to go — the console is where a
+    // team is managed once it syncs, and the CLI was the only thing that knew
+    // that and did not say it.
+    //
+    // The console is named only for the official endpoint. `browser.ts` pins that
+    // origin because it is a name we ship, and refuses to guess a self-hosted
+    // one — "its layout is not ours to know". Printing `app.<their domain>` would
+    // send an operator to a service that need not be theirs, so a self-hosted
+    // deployment gets the true half of the sentence and no invented URL.
+    const console_ = officialConsoleFor(config.baseUrl);
+    out(`\n"${opts.team}" is on this machine, unlocked and syncing. No further command to run` +
+        (console_ ? ` — manage it at ${console_}` : '') +
+        '.\n');
 }

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,38 +71,53 @@ 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';
     }
 }
+/**
+ * What a person types to ask their shell which executable would run.
+ *
+ * `where` on Windows, `which` everywhere else. Exported and taking its platform
+ * as an argument because this answer is now needed in two places and both of
+ * them are wrong if they disagree: this module RUNS it, and `login` PRINTS it
+ * for an operator to run themselves (#476). Telling a Windows reader to run
+ * `which` hands them a broken command at the exact moment they have hit the
+ * PATH confusion the message exists to resolve — raised in review.
+ *
+ * A parameter rather than a module-level constant so both branches are
+ * reachable from a test on one machine. A constant bound at import time can
+ * only ever be checked on the platform the suite happens to run on, which is
+ * the branch nobody needed to check.
+ */
+export function pathLookupCommand(on = platform) {
+    return on === 'win32' ? 'where' : 'which';
+}
 function onPath(command) {
     try {
         // `command -v` through the shell would re-interpret the name; execFile with
         // a fixed argv does not.
-        execFileSync(platform === 'win32' ? 'where' : 'which', [command], { stdio: 'ignore' });
+        execFileSync(pathLookupCommand(), [command], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -238,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
@@ -247,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.1",
+  "version": "0.1.3",
   "description": "Companion CLI for the agmsg cloud service: connect a team, join from another machine, and back up its keys.",
   "license": "UNLICENSED",
   "type": "module",